Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added documentation with Sphinx and reStructuredText #126

Merged
merged 63 commits into from Aug 11, 2018

Conversation

@mlwright84
Copy link
Contributor

mlwright84 commented Jul 10, 2018

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 .

@xoltar
xoltar approved these changes Jul 11, 2018
Copy link
Contributor

xoltar left a comment

Looks good, thanks for working on this!

@mlesnick

This comment has been minimized.

Copy link
Contributor

mlesnick commented Jul 14, 2018

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.

@mlesnick

This comment has been minimized.

Copy link
Contributor

mlesnick commented Jul 14, 2018

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.

@mlwright84

This comment has been minimized.

Copy link
Contributor Author

mlwright84 commented Jul 15, 2018

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.

mlesnick and others added 18 commits Jul 15, 2018
Lots of progress but still not near a local optimum.
This currently won't compile.

Created a Tikz figure showing the RIVET pipeline, including io capabilities.
TODO:
-clean up "running RIVET" and input data to better fit with the new documentation.
-Add a section output file formats.
-Perhaps write a subsection explicitly on coarsening.
…zation in the subpage structure.

Content still needs a lot of cleanup to fit this organization.
… progress and is currently a mess. Except for that, the draft of the new version of the documentation is pretty close to done.
…e content is still missing, however, especially about output formats.

Need to converge on make sure names for the file types are consistent.  (currently they are not.)
Added documentation todos.
mlwright84 and others added 28 commits Jul 31, 2018
@mlwright84 mlwright84 merged commit 94b0cf8 into rivetTDA:master Aug 11, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.