API Documentation

[Brad-eki]

Run some API documentation tools over the code so we have a browse-able and searchable reference.

[Brad-eki]

I am adding sphinx documentation to the project. The API documentation tool I'm using is autodoc.

It will be really useful to refactor a lot of our code such that autodoc can read it and produce meaningful API documentation.

I currently have this assigned to me, but would anyone else be able to give me a hand?

[Brad-eki]

Just figured out how to get sphinx autodoc to cover most of our code.

Doxygen might be better - it gives us the graphical maps of what goes where.

[Brad-eki]

Doxygen (with Graphviz dot) is great.

Do we want this as part of the repo, or are you happy making it yourselves?

[danielsjf]

So I guess we get something like this? Are there any consequences if we use this (e.g. changes in existing documentation, how does it handle docstrings etc.)

[Brad-eki]

We get something like that, yes. But next to signatures and attributes all mmapped (click-able links).

doxygen reads Python docstrings. If anything I'd encourage more use of docstrings.

Doesn't change existing doco. I am using it to get a visualization of what gets used where. It doesn't need to be a permanent feature as I think the sphinx/readthedocs autodoc stuff is easier to integrate with github.

It's up for discussion as the code is going through a substantial restructure and I find it helpful to have a graphical way of navigating the code. Also helps to see if something has changed substantially -- arrows move about.

I'm using it. I don't insist others will. It requires maintenance if it is to be used project-wide as the API doco would essentially need to be compiled for each PR.

[Brad-eki]

I have created a branch called refactor and have pushed a copy of the doxygen generated documents for the API with navigable SVG images.

In docs_api/html there is an index.html

[danielsjf]

@Brad-eki, if it makes the documentation better, I'm always in favour. I'm therefore fine with including this in the general code.