From fde2a59b0eba533f279dc105c142423137419cff Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 2 Feb 2020 19:05:35 -0500 Subject: [PATCH] update documentation for contributing files and building the manual to using rst files --- doc/src/Manual_build.rst | 9 +++++---- doc/src/Modify_contribute.rst | 15 ++++++++++++--- doc/utils/sphinx-config/false_positives.txt | 2 ++ 3 files changed, 19 insertions(+), 7 deletions(-) diff --git a/doc/src/Manual_build.rst b/doc/src/Manual_build.rst index 49f4d18097..22160a4d88 100644 --- a/doc/src/Manual_build.rst +++ b/doc/src/Manual_build.rst @@ -30,10 +30,11 @@ a. You can "fetch" the current HTML and PDF files from the LAMMPS web site. you update your local repository). b. You can build the HTML and PDF files yourself, by typing "make - html" followed by "make pdf". Note that the PDF make requires the - HTML files already exist. This requires various tools including + html" followed by "make pdf". This requires various tools including Sphinx, which the build process will attempt to download and install - on your system, if not already available. See more details below. + into a virtual environment in the folder doc/docenv, if not already + available. See more details below. To generate the PDF version of + the manual, additionally PDFLaTeX and several LaTeX packages are required. ---------- @@ -56,7 +57,7 @@ the doc dir. make clean # remove intermediate RST files created by HTML build make clean-all # remove entire build folder and any cached data make anchor_check # check for duplicate anchor labels - style_check # check for complete and consistent style lists + make style_check # check for complete and consistent style lists make spelling # spell-check the manual diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 73612d69c2..5e20d5c6bb 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -92,6 +92,7 @@ examples. If you are uncertain, please ask. need to test compiling LAMMPS from scratch with -DLAMMPS\_BIGBIG set in addition to the default -DLAMMPS\_SMALLBIG setting. Your code will need to work correctly in serial and in parallel using MPI. + * For consistency with the rest of LAMMPS and especially, if you want your contribution(s) to be added to main LAMMPS code or one of its standard packages, it needs to be written in a style compatible with @@ -114,12 +115,14 @@ examples. If you are uncertain, please ask. structures, performs its operations, and is formatted similar to other LAMMPS source files, including the use of the error class for error and warning messages. + * If you want your contribution to be added as a user-contributed feature, and it's a single file (actually a \*.cpp and \*.h file) it can rapidly be added to the USER-MISC directory. Send us the one-line entry to add to the USER-MISC/README file in that dir, along with the 2 source files. You can do this multiple times if you wish to contribute several individual features. + * If you want your contribution to be added as a user-contribution and it is several related features, it is probably best to make it a user package directory with a name like USER-FOO. In addition to your new @@ -132,7 +135,7 @@ examples. If you are uncertain, please ask. and Install.sh files in other USER directories as examples. Send us a tarball of this USER-FOO directory. - Your new source files need to have the LAMMPS copyright, GPL notice, +* Your new source files need to have the LAMMPS copyright, GPL notice, and your name and email address at the top, like other user-contributed LAMMPS source files. They need to create a class that is inside the LAMMPS namespace. If the file is for one of the @@ -142,14 +145,15 @@ examples. If you are uncertain, please ask. same stylistic format and syntax as other LAMMPS files, though that would be nice for developers as well as users who try to read your code. + * You **must** also create a **documentation** file for each new command or style you are adding to LAMMPS. For simplicity and convenience, the documentation of groups of closely related commands or styles may be combined into a single file. This will be one file for a single-file feature. For a package, it might be several files. These are text files with a .rst extension using the - :ref:`reStructuredText `_ markup language, that are then converted to HTML - and PDF using the :ref:`Sphinx `_ documentation + `reStructuredText `_ markup language, that are then converted to HTML + and PDF using the `Sphinx `_ documentation generator tool. Running Sphinx with the included configuration requires Python 3.x. Configuration settings and custom extensions for this conversion are included in @@ -177,6 +181,7 @@ examples. If you are uncertain, please ask. of references all styles in their corresponding tables and lists is run. In case the spell check reports false positives they can be added to the file doc/utils/sphinx-config/false_positives.txt + * For a new package (or even a single command) you should include one or more example scripts demonstrating its use. These should run in no more than a couple minutes, even on a single processor, and not require @@ -184,6 +189,7 @@ examples. If you are uncertain, please ask. examples of input scripts other users provided for their packages. These example inputs are also required for validating memory accesses and testing for memory leaks with valgrind + * If there is a paper of yours describing your feature (either the algorithm/science behind the feature itself, or its initial usage, or its implementation in LAMMPS), you can add the citation to the \*.cpp @@ -204,3 +210,6 @@ Finally, as a general rule-of-thumb, the more clear and self-explanatory you make your documentation and README files, and the easier you make it for people to get started, e.g. by providing example scripts, the more likely it is that users will try out your new feature. + +.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html +.. _sphinx: https://sphinx-doc.org diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 32274c853d..bd44de0761 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -634,6 +634,7 @@ dnf DNi Dobson Dodds +docenv dodgerblue dof doi @@ -2510,6 +2511,7 @@ Rr rRESPA Rspace rsq +rst rstyle Rubensson Rubia