Documentation

[yuki462-b]

What this PR does / why we need it

I have created a documentation for oper8.

It currently has descriptions of functions, classes, return values and input types. And they can be searched via UI.

Those are generated from docstrings, and the build is also automated with github workflow, so all the dev need is to write some docstrings, and merge codes into main branch, then the document should be updated automatically.

Documentations are written under docs folder.

• docs/API References.md
• docs/index.md

And github workflow is added to automatically publish the documentation to GitHub pages.

• .github/workflows/publish-document.yml

Currently it is not published yet. In order to view the documentation locally, please follow [Optional] Documentation setup at CONTRIBUTING.md. Below are the screenshots of the documentation.

The following tools are used:

• mkdocs: https://github.com/mkdocs/mkdocs/tree/master
• mkdocs material (material theme wrapper for mkdocs): https://github.com/squidfunk/mkdocs-material
• mkdocstrings (plugin to automatically generate documentation from docstrings): https://github.com/mkdocstrings/mkdocstrings

Special notes for your reviewer

I would like to publish this documentation using github pages, but it seems I do not have necessary permission to do so. The setting is written at .github/workflows/publish-document.yml, so please setup the github pages if you can.

Also, feel free to update the documentation. I think we need something like getting started page to give user some simple examples to show how to use oper8. I would like to write this page by myself, but to be honest, I don't understand this library that well ..., so someone please make the page, or give me some advice 🙏.

If applicable**

• this PR contains documentation
• this PR has been tested for backwards compatibility

What gif most accurately describes how I feel towards this PR?

[gabe-l-hart]

Thank you so much for adding this @yuki462-b! I've got a few suggestions around the automation and dependency tracking, but this is a great start for getting more visibility into the codebase.

[gabe-l-hart]

I don't think we need master in here

[yuki462-b]

I agree. Removed with this commit 89b0527.

[gabe-l-hart]

It would great to put all of this into pyproject.toml as an additional dev dependency set and then add a script in scripts to run the generation locally. This would allow us to dry-run docs easily locally which would be really useful if this docs section grows beyond auto-generated API references.

[yuki462-b]

Thank you for the advice!

I have updated pyproject.toml, tox.ini and added a shell script scripts/document.sh. Now, user can just run tox -e docs to build the current documentation, or tox -e docs -- serve to view the docs locally. 457dbf4

.github/workflows/publish-document.yml also uses tox command to publish the documentation. 4b27576

[gabe-l-hart]

I think we want to remove the leading / since I'm guessing this absolute path is only correct if developing inside a docker container

[yuki462-b]

I am sorry, but I don't understand which docker container you are mentioning.

I do not use docker container for my development environment. I simply followed CONTRIBUTION.md, and it does not have any description for docker.

And when I build the document with mkdocs build command, it outputs the document into /site folder, so I updated gitignore to ignore this directory.

Is there a way to create the development environment with docker?

[gabe-l-hart]

If we do go the route or scripting and tracking deps in pyproject this will need to be updated

[yuki462-b]

I don't think we have to chose this route. Please check #147 (comment)

[yuki462-b]

@gabe-l-hart
Thank you for the review. I have addressed all of your comment, so could you take a look again when you have time?

[gabe-l-hart]

Ship it! This looks great