documentation about brainglobe-atlasapi

[FedeClaudi]

related to the ongoing discussion over here: #40 (comment)

It would be good if the docs included a table with an overview of available atlases

[FedeClaudi]

Hey, do you want to open an issue in pydoc2md with suggestions for improving things?

[vigji]

Youp! I was waiting for it (writing docs) a bit as I guess that in these first times of development and testing on our side things might change fast and in my experience it's quite easy to forget outdated docs around.

I personally don't like much the sphinx/reST format and would prefer either Numpy or Google format + napoleon sphinx tool. It should be possible to convert the docs format from one version to the other using something like this although I have not tried!
But I have no strong opinion there and would comply to the sphinx/reST format if you like it more

[adamltyson]

I was thinking that writing docs could be more useful for development (so that other developers can better understand what things do).

I also don't have a strong opinion about the docstring format. My main reason is that amap/cellfinder etc use reST, but as long as it's one of the ones that PyCharm can do automatically, I don't mind.

[FedeClaudi]

I don't mind either, as long as I don't have to manually change brainrender's format. I did that a while ago to start using reST and it's not fun :P

[FedeClaudi]

I don't have much experience with this kind of documentation, but building it with sphinx from the docstrings seems like the easiest way

@adamltyson @vigji is this what we're going for in the end?

[adamltyson]

I think so. I think I would favour API docs automatically generated from the docstrings, in addition to a small amount of manually edited markdown illustrating general concepts, and any user-facing command-line tools.

[vitay]

any news on that front? I am reviewing for JOSS and that is the only problem I see. At least the docstrings of the BrainGlobeAtlas class should be exposed in the documentation (although help(BrainGlobeAtlas) does the job).

On a more minor note, one item for the review is:

Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

It is quite implicit as the code is on github, but perhaps you can add a small paragraph to the README so I can check off the item.

[FedeClaudi]

Hi,

I've added a short paragraph to the README (on the main branch) and to the docs with very simple guidelines for contributing.

Regarding the docstrings, I have generate docs like these for brainrender and added them to the docs online: https://docs.brainglobe.info/autogenerate-docs/bg_atlas/core

Hope this is what you had in mind, but please do let use know if there is a better way to document this.

[vitay]

Great, thanks!

[vigji]

I guess we can close this. Long term there's some aesthetical improvements that can happen on the markdown generated docs but that is minor