Remove all Sphinx Warnings: Generated Files are Missing References #117
Labels
documentation
Related to documentation
Milestone
Comments
This was referenced Sep 20, 2024
michael-christen
added a commit
that referenced
this issue
Sep 20, 2024
## Description Followed many twists and turns, but have documentation being generated and published to https://michael-christen.github.io/toolbox/ ! Changes were largely based around getting an initial doc tree setup, configuring various plugins, and getting published. - Configuring doc generation to work with bazel by exporting ALL python_sources as a secondary set of files via `filegroup`s. I'm not a huge fan of this / prevents usage of the existing `py_*` targets and in general the cache gets invalidated fairly easily. - Pulled a random icon of a wrench from https://www.flaticon.com/free-icon/wrench_4449037 - Vendored the autoapi templates for control over generated documentation - Working around a summary issue by modifying the autoapi templates: - https://bylr.info/articles/2022/05/10/api-doc-with-sphinx-autoapi/ - readthedocs/sphinx-autoapi#298 - add `publish-docs` workflow to publish docs when committing to master - fixed a `.gitignore` of the `build/` directory - added a bunch of sphinx dependencies - vendored in https://github.com/agoessling/rules_sphinx/tree/3280f704d048dd85400334f7513d0ce11bcdc5f3 to build doc html with bazel We're using a few tools: - https://github.com/peaceiris/actions-gh-pages for publishing to github pages - readthedocs is a nice alternative that could get us mutliple version support: https://app.readthedocs.org/projects/mchristen-toolbox & https://docs.readthedocs.io/en/stable/builds.html (though I wasn't able to get the bazel build working, I think I need to install go as a system dependency, then bazelisk with that, tbd) - https://myst-parser.readthedocs.io/en/latest/ is a pretty neat extension to sphinx that allows you to write most of your documentation in markdown, I've added a few examples for now - for documenting python docstrings we've got: https://github.com/readthedocs/sphinx-autoapi which is a definite improvement over https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html, though looking into https://github.com/sphinx-extensions2/sphinx-autodoc2#design-and-comparison-to-sphinx-autoapi could be interesting Followups: - [Integrate with C++ autodocs (doxygen) and rust / rustdoc](#115) - [Consider only running with bazel, not building as well](#116) - We seem to lose all references to generated code; not sure if that's ok or not, but it does prevent us from treating warnings as errors #117 - #118 - #119 - #120 - #121 - #122 ## Instructions - To add new python files - ensure `python_sources` created in the BUILD file and included in `//docs:docs` sources - if new directory, add to `autoapi_dirs` in `docs/conf.py` - To add new sphinx extensions, modify `docs/conf.py`, add to dep of `//tools/sphinx:sphinx_build_wrapper` ## Test Plan ``` bazel build //docs:docs xdg-open bazel-bin/docs/docs_html/index.html ``` To build and open the docs locally.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We can't get some of our generated files working, ideally we could
--fail-on-warningin our sphinx generation. This is preventing us.The text was updated successfully, but these errors were encountered: