Auto-generate code documentation

EvanKirshenbaum commented 7 months ago

Use external library to auto-generate code documentation

Migrated from internal repository. Originally created by Rares Vernica on Mar 24, 2022 at 5:31 PM PDT.

EvanKirshenbaum commented 7 months ago

This issue was referenced by the following commit before migration:

7e95a28795162ab01d3ba8ded96300b50f7743e2 by @EvanKirshenbaum on Apr 04, 2022 at 10:11 AM PDT

EvanKirshenbaum commented 7 months ago

Auto-generated docs are currently in https://pages.github.azc.ext.hp.com/evan-kirshenbaum/thylacine/

Migrated from internal repository. Originally created by Rares Vernica on Apr 01, 2022 at 4:13 PM PDT.

EvanKirshenbaum commented 7 months ago

I see that you pushed the change to .gitignore. What was it you had to do to make it so the CSS files got seen, and does that need to be pushed as well?

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 01, 2022 at 4:28 PM PDT.

EvanKirshenbaum commented 7 months ago

The change to make the CSS files work is in the doc branch. It is already there. It has been added in this commit. The change is in the html directory and can't be merged in the master.

Migrated from internal repository. Originally created by Rares Vernica on Apr 01, 2022 at 4:44 PM PDT.

EvanKirshenbaum commented 7 months ago

Here is a reference to fixing the CSS issue https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#static-site-generators

Migrated from internal repository. Originally created by Rares Vernica on Apr 01, 2022 at 4:55 PM PDT.

EvanKirshenbaum commented 7 months ago

Following the instructions here, I've modified the standard templates for modules and classes to generate member information.

It all seems to work, but it gives me a whole load of errors, all of the form either

D:\dmf-git\thylacine\mpam\src\mpam\device.py:docstring of mpam.device.Pad:1: WARNING: duplicate object description of mpam.device.Pad, other instance in stubs/mpam.device, use :noindex: for one of them

or

D:\dmf-git\thylacine\mpam\doc\stubs\mpam.device.Pad.rst:42: WARNING: autosummary: failed to import Pad.broken.

(always zero or more of the first followed by one of the second). I really have no clue what it's complaining about, but even though I'm typically an "absolutely no warnings allowed" kind of guy, unless I can figure this out rather quickly, I'm going to let these go and merge this into the master branch so that I can get on with the task of actually adding documentation comments.

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 04, 2022 at 10:51 AM PDT.

EvanKirshenbaum commented 7 months ago

I also cloned sphinx-build into tools/build_doc.py so that the documentation can easily be built from an IDE.

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 04, 2022 at 10:52 AM PDT.

EvanKirshenbaum commented 7 months ago

I think the warning are because the environment is dirty from the other builds. Try make clean first.

Migrated from internal repository. Originally created by Rares Vernica on Apr 04, 2022 at 10:54 AM PDT.

EvanKirshenbaum commented 7 months ago

I already tried that. It didn't help. I also nuked the files in the stubs dir (which make clean doesn't). Didn't help.

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 04, 2022 at 10:56 AM PDT.

EvanKirshenbaum commented 7 months ago

Hmm... Once the initial documentation is built, if you actually add a doc comment and rerun, the warnings don't reappear. Maybe we can live with this (at least for a while).

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 04, 2022 at 11:10 AM PDT.

EvanKirshenbaum commented 7 months ago

In #81, I've worked my way through adding Sphinx docstrings to mpam.types. It took longer than I expected, but I think I've now figured it out, and it should go faster in the future.

In the process, I've changed the Sphinx theme to "Read the Docs", which I think looks a fair bit nicer for API documentation. To use it, it needs to be installed using pip:

$ pip install sphinx-rtd-theme

There is a bug(?) in their presentation that prevents line wrapping, but I found a fix here, and it can be found in doc/_static/theme_overrides.css.

I also played around a bit with the templates themselves, mostly to distinguish between locally-defined and inherited attributes and methods. The revised templates can be found in doc/_templates.

There are still a few rough spots that need to be worked out, but I think it'll do for now. In particular,

The class pages list inherited methods and attributes but don't link to them. They'll link to local copies if you add "inherited-members" to autodoc_default_options in conf.py, but if you do that, you get lots of unnecessary hits when searching, since it thinks that the attributes/methods show up in every class.
We still get (hundreds of) warnings in between the two main Sphinx passes. They don't seem to actually indicate a problem, but I don't know how to get rid of them.

I've merged the Sphinx setup changes and the mpam.types documentation into master. I'll now start pushing through with documenting the rest of the system.

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 10, 2022 at 4:02 PM PDT.

EvanKirshenbaum commented 7 months ago

sphinx-rtd-theme should be added to requirements.txt

Migrated from internal repository. Originally created by Rares Vernica on Apr 11, 2022 at 4:50 PM PDT.

EvanKirshenbaum commented 7 months ago

Who's the audience for requirements.txt? It's only required for developers who plan on generating documentation. It isn't needed to simply run the code. I haven't looked closely at the spec for that file (wrt pip). Is there any notion of being able to break it into use cases?

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 11, 2022 at 4:53 PM PDT.

EvanKirshenbaum commented 7 months ago

Besides, requirements.txt isn't actually in the master branch yet. :-)

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 11, 2022 at 4:55 PM PDT.

EvanKirshenbaum commented 7 months ago

It is for the developers. For users we should list the requirements in a setup.py file. See here: https://packaging.python.org/en/latest/discussions/install-requires-vs-requirements/

install_requires is a setuptools setup.py keyword that should be used to specify what a project minimally needs to run correctly.

Whereas install_requires defines the dependencies for a single project, Requirements Files are often used to define the requirements for a complete Python environment.

Migrated from internal repository. Originally created by Rares Vernica on Apr 11, 2022 at 4:56 PM PDT.

EvanKirshenbaum commented 7 months ago

The warnings we are seeing might be due to this bug https://github.com/sphinx-doc/sphinx/issues/7817

Migrated from internal repository. Originally created by Rares Vernica on Apr 11, 2022 at 4:57 PM PDT.

EvanKirshenbaum commented 7 months ago

We probably want to add mpam.exerciser to index.rst as well so it gets documented.

Migrated from internal repository. Originally created by Rares Vernica on Apr 11, 2022 at 6:00 PM PDT.

EvanKirshenbaum commented 7 months ago

_ASF_Thread seems to be ignored by Sphinx. Probably because it starts with _

Migrated from internal repository. Originally created by Rares Vernica on Apr 14, 2022 at 4:21 PM PDT.

EvanKirshenbaum commented 7 months ago

If I add :meta public: to its docstring, it will show up (in full) on the mpam.device page (and in searches), but even then it won't show up on its own page or in the summary tables (including the left-hand ToC column). This is apparently a known Sphinx bug.

Migrated from internal repository. Originally created by @EvanKirshenbaum on Apr 14, 2022 at 4:41 PM PDT.

EvanKirshenbaum commented 7 months ago

@EvanKirshenbaum Can you please add this link https://pages.github.azc.ext.hp.com/evan-kirshenbaum/thylacine/ to the About section of the project in GitHub. This way we can quickly access the docs. Just click on the No description, website, or topics provided. text and paste it there.

Migrated from internal repository. Originally created by Rares Vernica on Jun 13, 2022 at 11:56 AM PDT.

EvanKirshenbaum commented 7 months ago

Done.

Migrated from internal repository. Originally created by @EvanKirshenbaum on Jun 13, 2022 at 11:59 AM PDT.

EvanKirshenbaum commented 7 months ago

After we moved the repository to DMFSoftware the docs are available here https://pages.github.azc.ext.hp.com/DMFSoftware/thylacine/ I updated the link in the About section of the repository.

HPInc / HP-Digital-Microfluidics