Create ReadTheDocs documentation for KPP

[yantosca]

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:

pandoc -f latex -t rst kppUserManual.tex -o kpp_UserManual.rst

and there will of course be some hand editing.

Testing of the documentation can be done with the sphinx-autobuild

conda activate base
(base) cd docs
(base) $sphinx-autobuild source build/html

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.

[RolfSander]

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.

[yantosca]

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

[yantosca]

I just re-pointed the ReadTheDocs to the our new KPP repository. See https://kpp.readthedocs.io/

[yantosca]

Also I think you can generate a PDF from the readthedocs site

[RolfSander]

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.

[yantosca]

See PR #41

[msl3v]

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.

[msl3v]

On the page "Input for KPP", the paragraph starting with "The kinetic description files contain a detailed specification... " is not clear.

[yantosca]

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.

[yantosca]

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

[RolfSander]

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.

[yantosca]

Indeed! I will close out this issue now.

[msl3v]

Hey. Is it correct that "n" is a superscript in Table 20?

[msl3v]

Also should we add a brief statement on the updating of the other languages?

[RolfSander]

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?