Built API docs from the docstrings using Sphinx+autodocs

[thisisrick25]

Introduce a script to fetch external repositories for the Brainglobe project, update Sphinx configuration for improved documentation paths and extensions, and enhance the API documentation for the brainglobe-atlasapi module. Include setup instructions for Python and external packages in the Sphinx build workflow.

closes #4

[thisisrick25]

@adamltyson I have added docs only for brainglobe-atlasapi, for now.
Sphinx cannot directly import and document code from remote GitHub repositories. It requires the actual Python packages/source code to be present locally so it can import them and extract docstrings.
I wrote fetch_external.py, which will clone and install the BG repos and added it to the workflow.

[adamltyson]

Thanks @thisisrick25. Do you need any feedback at this stage? Or shall we wait until all the repos are included in this PR?

[thisisrick25]

I am facing a problem @adamltyson. I can generate the docs in my local environment, but when I implement them in GA workflow, neuroinformatics-unit/actions/build_sphinx_docs interferes with my additional action setup. The action performs its own checkout potentially into a clean state/overwriting the workspace, not preserving the external dir.

One way I have yet to try is to write a completely different workflow action independent of neuroinformatics-unit/actions/build_sphinx_docs.

[adamltyson]

That action is maintained by us (https://github.com/neuroinformatics-unit/actions/tree/main/build_sphinx_docs), so if you can work out what needs to be changed, you're welcome to submit a PR.

[thisisrick25]

I will open a new issue @neuroinformatics-unit/actions

edit: issue neuroinformatics-unit/actions#83

[thisisrick25]

@adamltyson I want to point out that the docstring syntax is inconsistent in brainglobe-atlasapi (have not checked in other repos). I got this warning locally

which also throws an error in GA because of this -W flag (see logs here)

I checked by fixing the syntax and can confirm it works as expected.

Do we need the -W flag to build Sphinx doc for the API workflow? My conscience says yes, but it will take some time to fix the docstrings.

I'm not very familiar with how pre-commit works, but I think it might be possible to create a hook with the numpydoc repo to check the docstring for numpydoc validation. This would be helpful in the future.

[alessandrofelder]

Thanks @thisisrick25 - you make some good points here.

I want to point out that the docstring syntax is inconsistent in brainglobe-atlasapi (have not checked in other repos).

Indeed, this is expected (a consequence of BrainGlobe's "organic" growth) and would be nice to fix.

Do we need the -W flag to build Sphinx doc for the API workflow? My conscience says yes, but it will take some time to fix the docstrings.

I agree.

I'm not very familiar with how pre-commit works, but I think it might be possible to create a hook with the numpydoc repo to check the docstring for numpydoc validation. This would be helpful in the future.

I don't know either, but agree it should be possible, and would be helpful.

To help keep things tidy and manageable, I would tackle each point in a separate PR, in the following order

1. a PR that only fixes docstrings
2. this PR (and make sure things work)
3. a pre-commit PR (if possible)

Does that make sense, and would you have capacity to try (for this repo only)?

[thisisrick25]

@alessandrofelder Yes I will be happy to help.