This PR is intended to lay the groundwork for autogenerated Sphinx documentation. The idea is that the new Github action will build out HTML documentation for the entire package based on the function signatures and docstrings present in each module, and then publish that through Github Pages. The documentation is automatically generated, so we can focus on just maintaining the README and the docstrings the way we want them, and we'll be able to see them both in the code and through the website.
I tested the sphinx building step on my computer and after much back and forth got it looking correct. But I haven't directly tested the github action since I'm not sure how to do that before actually merging the PR. But you can see the main idea here.
After this goes live, the next step is to edit and adjust the readme and docstrings to better match the sphinx format and include as much useful and up-to-date information as possible. But I'm leaving that for the next PR for the sake of simplicity.
Specific details:
Will test and refine the action after merging; just wanted to show the general idea
Filled in a full boilerplate .gitignore file and added a bit to ensure it only captures the essential Sphinx files
Converted the README from markdown to reStructured Text format, which is seamlessly compatible with Sphinx and also Github. I didn't adjust the content of the file yet, just the format.
Added various Sphinx config files: don't worry too much about reviewing those because I tested them
Added a very simple index.rst file that generates the site by bringing in the README and then including the auto-generated API reference. When you click the link under API Reference in the built docs, it will take you to another page where you can see all the modules and all their subfunctions with all their docstrings, etc. Private functions (like _get) are not included.
Ran into an issue with Sphinx not treating Prefect tasks as functions, so after much research and trial, I came up with task_autodoc.py module which acts as a Sphinx extension to ensure that Prefect tasks are documented correctly.
This doesn't impact the actual package and so I don't think I will create a release for it or anything. Just merge. Then a future release can include rewrites/improvements of docstrings until everything looks beautiful.
This PR is intended to lay the groundwork for autogenerated Sphinx documentation. The idea is that the new Github action will build out HTML documentation for the entire package based on the function signatures and docstrings present in each module, and then publish that through Github Pages. The documentation is automatically generated, so we can focus on just maintaining the README and the docstrings the way we want them, and we'll be able to see them both in the code and through the website.
I tested the sphinx building step on my computer and after much back and forth got it looking correct. But I haven't directly tested the github action since I'm not sure how to do that before actually merging the PR. But you can see the main idea here.
After this goes live, the next step is to edit and adjust the readme and docstrings to better match the sphinx format and include as much useful and up-to-date information as possible. But I'm leaving that for the next PR for the sake of simplicity.
Specific details:
This doesn't impact the actual package and so I don't think I will create a release for it or anything. Just merge. Then a future release can include rewrites/improvements of docstrings until everything looks beautiful.