Feature Request: GitHub Pages Documentation Deploy with Latest Documentation Via CI

[jgarte]

Hi,

What do you think of CI building the latest GitHub Pages Documentation Release like there is here:

https://uqbar.readthedocs.io/en/latest/api/

I'd make a PR but I think this requires enabling fiddling with settings in the admin panel for your account iirc

[josiah-wolf-oberholtzer]

Docs are already built and pushed to gh-pages on every release. See here: https://github.com/josiah-wolf-oberholtzer/uqbar/blob/main/.github/workflows/publish.yml#L57-L82

I think that's good enough for me.

[josiah-wolf-oberholtzer]

Reminds me that I need to delete the ancient readthedocs version.

[josiah-wolf-oberholtzer]

Readthedocs has been retired ☠️

[jgarte]

That's awesome! But what happened to all of the fancy graphviz class diagrams in the uqbar docs similar to https://abjad.github.io/api/abjad/pcollections.html#module-abjad.pcollections?

Is it possible to auto distribute the PDF version of the uqbar docs also through your website? 😀

[josiah-wolf-oberholtzer]

The inheritance diagrams don't show up because I've suppressed them for Uqbar's docs.

It's possible to distribute the PDF, but I've chosen not to because the layout is significantly worse than the HTML version.

[josiah-wolf-oberholtzer]

You're welcome to check out the code and build the PDF version yourself.

[jgarte]

You're welcome to check out the code and build the PDF version yourself.

Would that be a make -C docs/ pdf in the root of the repo?

[jgarte]

Should a pdf: target be added to the Makefile in order to generate the PDF version?

[jgarte]

If so, I can open a PR for that ;()

[jgarte]

Or, this is just implicit functionality of a sphinx Makefile so advanced users should just read the sphinx docs to know how to generate the pdf for uqbar's documentation?

[jgarte]

Got it, thanx!

[josiah-wolf-oberholtzer]

And to be explicit:

• The Makefile is for developer tasks I personally use when working on the project
• The docs/Makefile is generated by Sphinx, and provides a variety of targets (which may work or not to varying degrees)
• I don't personally care about any of those sphinx-build targets except for clean and html
• You're welcome to try to build the docs in any of the formats that Sphinx supports, but I will not attempt to make any guarantees or put any effort into any of them besides html

[jgarte]

The inheritance diagrams don't show up because I've suppressed them for Uqbar's docs.

Hi @josiah-wolf-oberholtzer

What is the option to enable the inheritance diagrams?

[josiah-wolf-oberholtzer]

Inheritance diagrams are generated by the uqbar.sphinx.inheritance Sphinx extension.

The ReST directive to create one in an .rst file looks like:

.. inheritance-diagram:: your.module.path.here

If you want Uqbar's automatic Sphinx API generation to include them, set uqbar_api_module_documenter_class = "uqbar.apis.ImmaterialModuleDocumenter" in your Sphinx conf.py.

[jgarte]

Thanks! I'll give that a try soon with a Python project I'm working on.