Dear LAMMPS developers,
We are trying to add a new pair style to the LAMMPS. According to the manual, the documentation shall be written in .rst file using only ASCII characters and translated to PDF files via sphinx and PDFLaTeX. Is there anyone who have experience in this case and guide us how to write these files.
Actually, there are a lot of .rst files within doc/src folder, but I could not find out how to write these files.
As you may know these files start with some indexes. What does they mean? How they are selected?
What about accelerators?
Excuse if my knowledge of LAMMMPS is not enough!
Any help in this case will be appreciated.
Thanks
The natural approach to this would be to try and pick an existing .rst file for a pair style that is somewhat similar to your new pair style (ideally a file that describes only one pair style, not multiple variants), make a copy of that file under a new name that matches the file name of your pair style and then modify its description and references so that it matches your pair style. Then you can look up where the original pair style doc file (and the corresponding pair style) are referenced and how and do the equivalent changes for your new file.
If you translate the entire manual including your new file to HTML (with “make html” in the doc folder), you may get warnings, if some details are not quite right from the checks that we have programmed or from sphinx. Then you can try to update your file accordingly.
Once that is converged and the HTML output page looks like you want it to be, you can check for spelling issues, and also test the PDF translation (with “make spelling” and “make pdf”). The latter will sometimes fail if your embedded math is not 100% compliant or there are issues with non-ASCII characters, inconsistent references etc. So you correct those, too.
In general, just use some common sense and don’t worry too much about making everything “perfect”. There is no harm in submitting incomplete documentation files or files with minor errors in a pull request because there are often suggestions for changes and then you will have to do everything all over again, so being only 95% finished is often much more effective and trying to be 100%. Since this is going to be your first submission and you are not yet very familiar with all the details, it is likely that there will be suggestions for changes.