sphinx api documentation

[AlbinaMuzafarova]

Description

make the sphinx-generated api documentation look better, have a nice table of contents, show the package tree in a sensitive way, show the model component docstrings in the right place, etc.

Todo

• [x] ToC should contain:

  • data_model
  • process_types
  • model components
  • models
  • runners
  • util
  • private

• [ ] For each model component, the main doc should be entered into the docstring of either __init__.py or model.py and then presented in the API doc on top of that model component's page

• [ ] improve variable presentation. For each variable used in a model component, there is an attribute in one of the classes in interface.py, storing an object of type variable that holds that variable's metadata. Sphinx currently uses the Variable class' __repr__ method (defined in data_model.variable) to produce the long italics string shown in the API doc. The API doc for each Variable should list its metadata in a nicer layout like a bullet list or the like.

• [ ] It would also be good if variables in a model component that are just copied from the master data model show a link in the API doc to their def. in the master model.

[AlbinaMuzafarova]

@leander-j @mensch72 since I am experiencing troubles generating the documentation from master, is this what you see when you generate the documentation currently?

The Index is empty and Module Index for API reference not found

[leander-j]

index.html looks similar:

The Index and Module Index are not empty though.

I noticed that on other branches (e.g. imitation_component/issue_152) at least the TOC structure is different:

[mensch72]

in my case both index and module index are populated. otherwise it looks the same. i'll send you a zip of the html folder.

Am 15. Dezember 2021 15:10:15 MEZ schrieb AlbinaMuzafarova @.>: @. @mensch72 since I am experiencing troubles generating the

documentation from master, is this what you see when you generate the documentation currently?

The Index is empty and Module Index for API reference not found

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/pik-copan/pycopancore/issues/159#issuecomment-994826662

-- Diese Nachricht wurde von meinem Android-Gerät mit K-9 Mail gesendet.

[AlbinaMuzafarova]

thank you! I'll compare the received html with mine for deviations and would be also curious to check the config file for the branch mentioned by @leander-j

[leander-j]

The screenshots were from the issue_152 branch, the html generated there is html.zip

[AlbinaMuzafarova]

@leander-j i've changed the depth of the table for issue_152 branch. It should be 1 now, same as for master (see #167).

@mensch72 @leander-j I think i'm generating the index and module index properly now, although there are still many errors in the terminal. Could you let me know if this is what you see (I've changed the theme, so please don't consider the difference in colors):

[leander-j]

Yes, it does look like that, just with way more modules/items. In fact so many that the Index page hides them

[AlbinaMuzafarova]

I've pushed first changes to doc/api branch. If someone could try generating the documentation locally on that branch, that'd be great.

Expected output: ToC with API reference which is populated according to the description

I've adapted the theme to Book theme because it handles presentation and navigation between pages/headings smoother than alabaster. To install, use pip install sphinx-book-theme

I suspect that due to me running Windows, sphinx is not working as smoothly as for the rest of the team. To double-check my assumptions, i'd hearing whether these parts of the API reference>Models page are filled:

[mensch72]

Hi Albina,

overall this looks much nicer than before! Thank you!!

I do have a number of fast observations:

• In the master data model, the Variables do no longer show up: file:///home/heitzig/Nextcloud/git/pycopancore/docs/_build/html/api/pycopancore/pycopancore.data_model.master_data_model.html#module-pycopancore.data_model.master_data_model.environment Before, each defined Variable was listed with its metadata. (Currently, the dimensions and units are shown, file:///home/heitzig/Nextcloud/git/pycopancore/docs/_build/html/api/pycopancore/pycopancore.data_model.master_data_model.html#module-pycopancore.data_model.master_data_model.dimensions_and_units and I imagine it similarly for Variables).
• It is somewhat unclear to me, where the section titles / headlines used in the APIdoc are coming from. E.g., in file:///home/heitzig/Nextcloud/git/pycopancore/docs/_build/html/api/pycopancore/pycopancore.data_model.master_data_model.html#module-pycopancore.data_model.master_data_model.dimensions_and_units where does the headline "Dimensions and units" come from, I can't find it in the source. I would suggest that sections for classes should always show the class name (rather than some part of the docstring), e.g. "DimensionsAndUnits" instead of ""Dimensions and units".
• We should find a way to distinguish "public" methods meant to be used by model users (like "run" in "Runner") from "private" methods only used internally in the framework (like "apply_explicits" in "Runner", see file:///home/heitzig/Nextcloud/git/pycopancore/docs/_build/html/api/pycopancore/pycopancore.runners.html#module-pycopancore.runners.runner).
• Parameters of class constructors sometimes do not seem to appear in the doc, e.g. in "Runner", the parameter descriptions of "model" and "termination_calls" in the docstring don't seem to appear.
• For model components, it is still not clear to me, where the natural place for introductory text that will then shows up at the top of the page would be. Either of the following places could seem natural, but I don't know how to make Sphinx show them at the top of the model component page:
  • a dedicated README.md file in the subpackage folder
  • the module docstring in "init.py", "model.py" or "interface.py"
  • the class doctring of "Model" in model.py

[AlbinaMuzafarova]

thank you Jobst for your first feedback! I'll gradually walk my way commenting on issues I have some clues on first:

For model components, it is still not clear to me, where the natural place for introductory text that will then shows up at the top of the page would be.

Currently, sphinx looks at _init_.py file and present the docstring on the top of the model component/any other page. So I would suggest we keep using that location for general descriptions.

[AlbinaMuzafarova]

It is somewhat unclear to me, where the section titles / headlines used in the APIdoc are coming from

The headings were generated by sphinx first as paths and seemed unreadable to me, e.g. pycopancore/pycopancore.data_model.dimensions_and_units. So I've modified them manually for better user experience. I can adjust the subtitles to reflect the exact naming of the package/class in the next commit.

[AlbinaMuzafarova]

We should find a way to distinguish "public" methods meant to be used by model users (like "run" in "Runner") from "private" methods only used internally in the framework

I think sphinx has a flag to hide private methods. Would that be a desired solution here or were you thinking of finding just a visual distinction?

[mensch72]

that would be perfect

Am 31. Januar 2022 17:58:45 MEZ schrieb AlbinaMuzafarova @.***>:

We should find a way to distinguish "public" methods meant to be used by model users (like "run" in "Runner") from "private" methods only used internally in the framework

I think sphinx has a flag to hide private methods. Would that be a desired solution here or were you thinking of finding just a visual distinction?

-- Reply to this email directly or view it on GitHub: https://github.com/pik-copan/pycopancore/issues/159#issuecomment-1025996120 You are receiving this because you were mentioned.

Message ID: @.***>

-- Diese Nachricht wurde von meinem Android-Gerät mit K-9 Mail gesendet.