search

lumol-org / lumol

Universal extensible molecular simulation engine
http://lumol.org/
BSD 3-Clause "New" or "Revised" License
190 stars 18 forks source link

Input reference using sphinx #209

Closed g-bauer closed 6 years ago

g-bauer commented 6 years ago

This PR adds a separate manual to the doc directory: input_reference. This manual contains the input file references built with sphinx.

I changed the order of some entries we have in the current documentation. Also, I got rid of some repetition. It is not fleshed our yet and merely showing the structure which I want to discuss.

Build the docs

To build the manual, change to doc/input_reference and type

make html

to build a HTML documentation. To inspect the manual, open build/html/index.html. If you don't have the read_the_docs-theme installed you can switch themes by changing the html_theme entry inside source/conf.py.

Other builds are also supported by sphinx. To get an overview, simply type make without specifying the format.

Luthaf commented 6 years ago

I checked this PR locally, and the output looks great!

Maybe we can have the sources in an src directory instead of a source one to follow the same convention as the rest of the code ? We'll also need to put the build directory in a .gitignore.

g-bauer commented 6 years ago

I used sphinx' sphinx-quickstart, that's why it's called source 😄 I also have to change the name in the Makefile.

I checked this PR locally, and the output looks great!

And we get pdfs for free!

Luthaf commented 6 years ago

And we get pdfs for free!

Yay!

g-bauer commented 6 years ago

I restructured the manual a bit and I am really liking how it worked out. Sphinx fits our needs, I think (l mean you can even make a man that looks spectacular). I'd leave the PR as is (ready to merge from my side).

Luthaf commented 6 years ago

I pushed a few more commits moving things around and other formatting issue. The global diff must be unreadable due to 3f5486f0c1a921904da71c305730f3bdef8cbb8f and 08fbd17e6628dd7cf6c4436fc8bd8958c41b5775, but the commits diff should be OK.

The new version of the doc is not built or deployed to github pages with this, am I right? And the previous version is still here, right? If so, and if you agree with my last proposed changes, we can merge this and continue going forward on the conversion of all the doc to sphinx!

g-bauer commented 6 years ago

The new version of the doc is not built or deployed to github pages with this, am I right?

That's correct.

And the previous version is still here, right?

Yepp, currently both versions exist.

If so, and if you agree with my last proposed changes, we can merge this and continue going forward on the conversion of all the doc to sphinx!

I'll check out your changes later tonight and merge if that's ok for you.

Luthaf commented 6 years ago

Yep, thats fine for me!