Fix apidocs

[allemangD]

sphinx-apidoc is generating an empty docs for abcdmicro.run, even though it has gen_masks() click entrypoint with a docstring. I guess somehow the click decorators clobber the docstring and it won't work. I figure this is probably a good place to put documentation about the entrypoint CLIs themselves but I'm not yet sure how to do this.

I also looked into filtering out abcdmicro.run from the apidocs entirely. The easiest way to do this is to rename it to _run to mark it private, but then the wrapper script in SlicerBrainMicrostructure is accessing a private member. You can also explicitly list it in the arguments to sphinx-apidoc in .readthedocs.yml... this might be our best option if we want to do it.

Closes #24.

[allemangD]

https://github.com/click-contrib/sphinx-click works well, although it isn't picked up by sphinx autodoc. It seems sufficient to list the appropriate sphinx-click directive in the run module docstring. See 0dcccc371c15e176d6615acc9c9a934589a8203d.

And CLI help text doesn't include the :func: cross reference.

Usage: gen_masks [OPTIONS]

  Recursively find and process dwi images and create hd_bet masks for each.
  Preserves directory structure in output.

  Searches for input files: ``<ID>_dwi.nii.gz``, ``<ID>.bval``, ``<ID>.bvec``

  Produces output files: ``<ID>_b0.nii.gz``, ``<ID>_mask.nii.gz``

Options:
  -i, --inputs PATH   Root directory to search for inputs.  [required]
  -o, --outputs PATH  Root directory to write outputs.  [required]
  --overwrite         Recompute and overwrite existing output files.
  -j, --parallel      Compute intermediate ``<ID>_b0.nii.gz`` files in
                      parallel. Note that HD_BET does *not* compute in
                      parallel.
  --help              Show this message and exit.

[allemangD]

So the issue was that we were previously just doing sphinx-build and we had to do precede that with sphinx-apidoc?

nox -s build_api_docs
nox -s docs

Right. Or simply:

nox -s build_api_docs docs

But also then I wonder why they are separate steps. Why would the docs nox session just also do build_api_docs along the way.

nox -s docs probably could do it... those sessions already existed from the template and the control flow is a little tricky so I thought better to leave it as-is.

sphinx-apidoc generates a few rst files that then get picked up by sphinx-build. All the autodoc logic happens during sphinx-build. I guess the stages are separate so that it avoids regenerating rst and clobbering sphinx cache if the api structure hasn't changed. Docstrings and method names etc. still update without re-running sphinx-apidoc. It's just new/deleted modules that aren't updated.

I also imagine there are projects where the apidoc rst files gets checked into version control. My intuition is that's not a good idea though, better to keep things in-sync by adding it to readthedocs CI. If it turns out we regret that decision later - maybe we want to manually tweak the generated files - remove the docs/*.rst entry from .gitignore.

[allemangD]

Looks like everything on rtfd is working!

https://abcd-microstructure-pipelines.readthedocs.io/en/latest/py-modindex.html

https://abcd-microstructure-pipelines.readthedocs.io/en/latest/abcdmicro.run.html

[ebrahimebrahim]

yay!