Closed mlwright84 closed 6 years ago
Thanks for setting this up Matthew. Based on what I have seen so far, the Sphinx documentation looks really good, format-wise.
Content-wise, I don't feel this version of the documentation is quite ready to replace the old one (even keeping in mind the various defects of the earlier version) because it seems to be missing an introductory section which explains at a high level what the software does. This was accomplished to some limited extent by the "About" section and "Understanding the RIVET visualization" section in the earlier version, but the content of these now appears further back in the documentation.
So I would suggest that we work on the content a little more to address this, before doing the merge. I can do some work on this in the next few days.
Also, before merging, we should modify readme.md to eliminate redundant content and point to some compiled version of the documentation. The pointer could be to rivet.readthedocs.io, to rivet.online, or to a compiled copy of the documentation in the repo.
I agree with Mike's suggestions. We could make a page titled "About" or "Getting Started" with introductory content. We could also add some introductory text to the title page (the page that lists the contents).
Optionally, we could also flag key words in our documentation so that Sphinx will generate an index.
I've been doing a lot of work on the documentation over the last two weeks. What I have is still a draft, and needs more work --- I catalogued some remaining issues in a section at the bottom of about.rst.
But a new structure is finally starting to congeal, and I thought now would be a good time to share my progress. I merged my changes into Matthew's branch, so they now can be seen on readthedocs (though there seem some formatting problems, as mentioned in the todos.)
Documentation from rivet.online has been copied into the new docs folder and formatted in reStructuredText. Sphinx has been set up with a conf.py file. Documentation in the docs folder appears at https://rivet.readthedocs.io .