pages were nicely created using Sphinx
I used to use the Django framework for building the REST API to the TOAR database.
To have nice documentation pages, I could make use of the package “sphinxcontrib.django”,
which did a pretty good job (which you can see here: http://toar.pages.jsc.fz-juelich.de/toar-db/docs/).
In April this year we decided to switch to the FastAPI framework.
I searched the internet, whether there are also contributions from FastAPI to Sphinx, but I was not successful.
The pages, that were automatically created from the old (Django-)Sphinx scripts, did not look good (I found them even confusing).
To have at least a little bit of documentation, I now put some information about the database tables inside my docstrings (information about the database tables was not in the old documentation),
using table formatting to have a nice look -- but this is not the way you are advised to use docstrings and Sphinx.
First pages can be found here: http://toar.pages.jsc.fz-juelich.de/toardb_fastapi/docs/.
This is an example, what is (for me) most disturbing:
Old documentation:
http://toar.pages.jsc.fz-juelich.de/toar-db/docs/newDB.html#class-variable-model
From the first line you see, how the variable is build, and the section Parameters informs you about the types of the arguments.
New documentation:
http://toar.pages.jsc.fz-juelich.de/toardb_fastapi/docs/newDB.html#model-variable
Everything from the above advantages is missing.
The table and explanations you see first is from my docstring (you can see it, when clicking on “source”).
From the documentation, you have no clue, how “variables” is build, nor do you see the types of the arguments
-- and confusingly, the variable metadata is shown, which is not part of the class “Variable” itself.
The table, I added to the doc-string, is just a workaround. It was something I could easily get (without spending too much extra work) from the database. With these doc-strings, I have at least a little bit of informative documentation because I was unsatisfied with the result I got from the combination of Sphinx and FastAPI (but of course, this is not the way one works with doc-strings).
I have to find out if there is a contribution from FastAPI to Sphinx.