Documentation in ChiantiPy about chiantipy HOT 8 CLOSED

The closest thing to complete documentation is the API documentation created by Epydoc listed near the bottom of the page. The documentation is definitely incomplete.

I am aware of the Read the Docs site but I am unsure how this would make life easier for me. I will have to look into it but if you have a short answer that would be appreciated.

from chiantipy.

sorry, did not really mean to close the issue

from chiantipy.

I actually found the Epydoc documentation right after I posted this. Sorry for the oversight!

Sphinx (+Read the Docs) seems to focus both on API documentation as well as general installation information, tutorials, developer guides etc., (e.g. the Sunpy docs) while Epydoc is purely auto-generated API references.

Nothing wrong with that obviously, but maybe for the sake of maintainability and simplicity, moving to a purely Sphinx+Read the Docs implementation would allow the tutorial/installation guide and API to be generated all at the same time by the same engine. As a bonus, the two sections would also maintain the same styling/aesthetic.

Another benefit of Sphinx is easy integration with continuous integration services (e.g. Travis CI). In this way, the docs are automatically generated/pushed to Read the Docs anytime a push is made to a given branch (e.g. master). This may also be possible with Epydoc.

Just some suggestions. I would be willing to look into getting this setup.

from chiantipy.

At one point I was going to do the Docs by hand with Sphinx. I started and realized that would take much more time than I had. So I used Epydoc and, in the past, Eric's documentation mechanism. Obvioulsly I have not pointed out that the Epydoc stuff could be useful for users.

If you could look into how to set it up, that would be great.

from chiantipy.

After a bit more effort than I anticipated, here is a test Read the Docs page built using Sphinx and my fork of Chiantipy. No new documentation here really. I've just essentially copied all of the old docs from the SourceForge page and then added an API tab (it's labeled chianti for now, the auto-generated name) so that all of the API docs+intro, quickstart,tutorial, etc., are all on one page. Still very rough, but it is a nice start I think.

Read the Docs provides some nice features like rebuilding the docs at each commit to a given branch, automatic generation of PDF, ePub formats, and even more stuff that I haven't looked into fully.

There are still some issues with the implementation I have going now, namely that the API toctree has to be generated first "by hand" (i.e. not on the RTD server). Additionally, the wx GUI module is missing docs. I could not find a way to (easily) build the wx module on RTD so that's also a TODO.

Astropy provides some nice generalized templates and scripts for building really good looking API docs with Sphinx+RTD and it might be worth looking into integrating some of these to make the workflow a bit smoother. I believe this is the approach that the Sunpy team has taken.

from chiantipy.

looks good. Are the RTD docs generated from the online web github or from you fork of the chiantipy on your computer? The Epydoc generated documentation had to be redone for each new release so this should be much better.
thanks

from chiantipy.

RTD uses GitHub's web hooks to rebuild the documentation each time a commit is made to a given branch (e.g. master). So these docs are generated from the code committed to my fork of ChiantiPy on GitHub.

If you'd like to go ahead and start using RTD, I think the best way to go about this is for me to submit a pull request against the master branch of the main repo and then these changes can be merged in.

After that, you (or someone with admin privileges for the main ChiantiPy repo) will just need to create an account on RTD and add the main ChiantiPy repo as a project. The docs will then be built at the next commit.

from chiantipy.

sounds good. Why don't you go ahead and make a pull request

from chiantipy.