Closed yantosca closed 2 years ago
I've been thinking about the best way for presenting our documentation. I don't have any perfect answers, but at least here is some food for thought:
1) The presentation format: The main options seem to be PDF and HTML. Both have their advantages and disadvantages. PDF is a nice format for a printed document, while HTML is nice for on-screen reading. PDF is much more suitable for presenting mathematical equations (as, for example in the "Numerical methods" section of the User Manual). PDF can be generated easily via LaTeX, while HTML can be generated easily from ReST markup (https://en.wikipedia.org/wiki/ReStructuredText). I think it would be good to create both PDF and HTML. However, this will become unmaintainable soon unless we manage to generate both from the same master file.
2) The document structure: We currently have a very GEOS-Chem specific description at ReadTheDocs, and a generic KPP description in LaTeX. When merging the documents, we need to create a structure that combines both in a suitable way.
Thanks @RolfSander. I would propose moving the GEOS-Chem specific stuff to geos-chem.readthedocs.io, and just end up having a RTD translation of the existing kpp manual
I just re-pointed the ReadTheDocs to the our new KPP repository. See https://kpp.readthedocs.io/
Also I think you can generate a PDF from the readthedocs site
I would propose moving the GEOS-Chem specific stuff to geos-chem.readthedocs.io
Yes, this looks like the right place.
and just end up having a RTD translation of the existing kpp manual
Yes, that would be good. I hope there isn't too much to be done manually after the pandoc conversion.
Also I think you can generate a PDF from the readthedocs site
That's also an interesting option to explore.
See PR #41
I'm able to run the example. But it did not require copying anything into the dir. It appears simply creating the *.kpp file and setting #MODEL small_strato did all of the copying necessary. Also, Bob, please include a statement about needing to increase the stacksize to get KPP to generate the stoichiometry files.
On the page "Input for KPP", the paragraph starting with "The kinetic description files contain a detailed specification... " is not clear.
I'm able to run the example. But it did not require copying anything into the dir. It appears simply creating the *.kpp file and setting #MODEL small_strato did all of the copying necessary.
I just confirmed that! I guess KPP is smart enough to look for the files in $KPP_HOME
. I'll take out the copy commands but leave the other text.
Also, Bob, please include a statement about needing to increase the stacksize to get KPP to generate the stoichiometry files.
Will do! Slipped my mind.
FYI, if you click on at the bottom of the left bar on ReadTheDocs, you'll get this menu
and you can get a PDF version of the manual
Great to see that ReadTheDocs provides PDF generation as well! For our next release (2.6.0), I think we can delete the manual/ directory and include the ReadTheDocs-generated pdf instead.
Indeed! I will close out this issue now.
Hey. Is it correct that "n" is a superscript in Table 20?
Also should we add a brief statement on the updating of the other languages?
Is it correct that "n" is a superscript in Table 20?
Apparently, the superscript is used to refer to a certain time step. You can also find this notation in an old paper from Adrian:
10.1016/J.ATMOSENV.2003.08.019
Should we adopt this notation or try to use a subscript instead?
Overview
I have started adding the ReadTheDocs documentation for this repository in the feature/ReadTheDocs branch.
The kpp_UserManual.tex can be ported to ReST by this command:
and there will of course be some hand editing.
Testing of the documentation can be done with the sphinx-autobuild
which will build the documentation and serve the output to localhost:8000. This is best done on a local PC.
We can add discussion to this issue.