Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate Internal API documentation #110

Closed
3 tasks done
robons opened this issue Jul 28, 2021 · 2 comments
Closed
3 tasks done

Generate Internal API documentation #110

robons opened this issue Jul 28, 2021 · 2 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@robons
Copy link
Contributor

robons commented Jul 28, 2021

We should use an API documentation generation tool like Sphinx to generate the documentation we need to show what classes/functions are available/how they are related and any docstrings they have explaining their use.

  • Each project (devtools/sharedmodels/PMD/csvwlib) should generate their own docs.
  • A Jenkins job should be created to generate these docs, they should be output as a ZIP artifact for the build process.
  • The docs should be available as a (searchable) static HTML website.

Do we want to publish the static site somewhere or are we happy having a ZIP file to download at this stage? - We're happy enough with a ZIP for now.

@robons robons added the documentation Improvements or additions to documentation label Jul 28, 2021
@robons robons changed the title Generate internal API documentation Generate Internal API documentation Jul 28, 2021
@robons
Copy link
Contributor Author

robons commented Jul 29, 2021

@mikeAdamss has suggested we consider using mitmproxy/pdoc. Is worth considering using instead of sphinx when doing this ticket.

@robons robons self-assigned this Jul 30, 2021
robons pushed a commit that referenced this issue Jul 30, 2021
…entation being generated for all projects.
robons pushed a commit that referenced this issue Jul 30, 2021
…PI documentation being generated for all projects."

This reverts commit a151867.
robons pushed a commit that referenced this issue Jul 30, 2021
…in the API documentation being generated for all projects.""

This reverts commit 975f747.
@robons
Copy link
Contributor Author

robons commented Jul 30, 2021

Some useful links for managing the current sphinx configuration I have setup:

Each project's API documentation config file can be found in docs/conf.py. That's where we configure things like the function names which are ignored, the ordering of the functions/attributes in classes/modules and the intersphinx referencing.

robons pushed a commit that referenced this issue Aug 2, 2021
…in the API documentation being generated for all projects.""

This reverts commit 975f747.
robons pushed a commit that referenced this issue Aug 2, 2021
…ring Jenkins file documentation build to make use of those better titles.
@canwaf canwaf closed this as completed Aug 4, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants