ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation conventions. add notes about adding packages

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-12-30 06:45:08 -05:00
parent 3b9799410b
commit 406289d0f9
1 changed files with 62 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
doc/documentation_conventions.md
View File

@ -4,45 +4,44 @@ This purpose of this document is to provide a point of reference
for LAMMPS developers and contributors as to what conventions for LAMMPS developers and contributors as to what conventions
should be used to structure and format files in the LAMMPS manual. should be used to structure and format files in the LAMMPS manual.
Last change: 2020-04-23 Last change: 2022-12-30
## File format and tools ## File format and tools
In fall 2019, the LAMMPS documentation file format has changed from In fall 2019, the LAMMPS documentation file format has changed from a
a home grown minimal markup designed to generate HTML format files home grown markup designed to generate HTML format files only, to
from a mostly plain text format to using the reStructuredText file [reStructuredText](https://docutils.sourceforge.io/rst.html>. For a
format. For a transition period all files in the old .txt format transition period all files in the old .txt format were transparently
were transparently converted to .rst and then processed. The txt2rst converted to .rst and then processed. The `txt2rst tool` is still
tool is still included in the distribution to obtain an initial .rst included in the distribution to obtain an initial .rst file for legacy
file for integration into the manual. Since the transition to integration into the manual. Since that transition to reStructured
reStructured text as source format, many of the artifacts or the text, many of the artifacts of the translation have been removed though,
translation have been removed though and parts of the documentation and parts of the documentation refactored and expanded to take advantage
refactored and expanded to take advantage of the capabilities of the capabilities reStructuredText and associated tools. The
reStructuredText and associated tools. The conversion from the conversion from the source to the final formats (HTML, PDF, and
source to the final formats (HTML, PDF, and optionally e-book optionally e-book reader formats ePUB and MOBI) is mostly automated and
reader formats ePUB and MOBI) is mostly automated and controlled controlled by a Makefile in the `doc` folder. This makefile assumes that
by a Makefile in the `doc` folder. This makefile assumes that the the processing is done on a Unix-like machine and Python 3.5 or later
processing is done on a Unix-like machine and Python 3.5 or later
and a matching virtualenv module are available. Additional Python and a matching virtualenv module are available. Additional Python
packages (like the Sphinx tool and several extensions) are packages (like the Sphinx tool and several extensions) are transparently
transparently installed into a virtual environment over the installed into a virtual environment over the internet using the `pip`
internet using the `pip` package manager. Further requirements package manager. Further requirements and details are discussed in the
and details are discussed in the manual. manual.
## Work in progress ## Work in progress
The refactoring and improving of the documentation is an ongoing The refactoring and improving of the documentation is an ongoing
process, so statements in this document may not always be fully process, so statements in this document may not always be fully
up-to-date. If in doubt, contact the LAMMPS developers. up-to-date. When in doubt, contact the LAMMPS developers.
## General structure ## General structure
The layout and formatting of added files should follow the example The layout and formatting of added files should follow the example of
of the existing files. Since those are directly derived from their the existing files. Since many of those were initially derived from
former .txt format versions and the manual has been maintained in their former .txt format versions and the manual has been maintained in
that format for many years, there is a large degree of consistency that format for many years, there is a large degree of consistency
already, so comparison with similar files should give you a good already, so comparison with similar files should give you a good idea
idea what kind of information and sections are needed. what kind of information and sections are needed.
## Formatting conventions ## Formatting conventions
@ -52,21 +51,27 @@ It seems to be sufficient to have this consistent only within
any single file and it is not (yet) enforced strictly, but making any single file and it is not (yet) enforced strictly, but making
this globally consistent makes it easier to move sections around. this globally consistent makes it easier to move sections around.
Filenames, folders, paths, (shell) commands, definitions, makefile File names, folders, paths, (shell) commands, definitions, makefile
settings and similar should be formatted as "literals" with settings and similar should be formatted as "literals" with
double backward quotes bracketing the item: \`\`path/to/some/file\`\` double backward quotes bracketing the item: \`\`path/to/some/file\`\`
Keywords and options are formatted in italics: \*option\* Keywords and options are formatted in italics: \*option\*
Mathematical expressions, equations, symbols are typeset using Mathematical expressions, equations, symbols are typeset using
either a `.. math:`` block or the `:math:` role. either a `.. math:` block or the `:math:` role.
Groups of shell commands or LAMMPS input script or C/C++ source Groups of shell commands or LAMMPS input script or C/C++/Python source
code should be typeset into a `.. code-block::` section. A syntax code should be typeset into a `.. code-block::` section. A syntax
highlighting extension for LAMMPS input scripts is provided, so highlighting extension for LAMMPS input scripts is provided, so `LAMMPS`
`LAMMPS` can be used to indicate the language in the code block can be used to indicate the language in the code block in addition to
in addition to `bash`, `c`, or `python`. When no syntax style `bash`, `c`, `c++`, `console`, `csh`, `diff', `fortran`, `json`, `make`,
is indicated, no syntax highlighting is performed. `perl`, `powershell`, `python`, `sh`, or `tcl`, `text`, or `yaml`. When
no syntax style is indicated, no syntax highlighting is performed. When
typesetting commands executed on the shell, please do not prefix
commands with a shell prompt and use `bash` highlighting, except when
the block also shows the output from that command. In the latter case,
please use a dollar sign as the shell prompt and `console` for syntax
highlighting.
As an alternative, e.g. to typeset the syntax of file formats As an alternative, e.g. to typeset the syntax of file formats
a `.. parsed-literal::` block can be used, which allows some a `.. parsed-literal::` block can be used, which allows some
@ -89,22 +94,30 @@ by ` :class: note`.
## Required steps when adding a custom style to LAMMPS ## Required steps when adding a custom style to LAMMPS
When adding a new style (e.g. pair style or a compute or a fix) When adding a new style (e.g. pair style or a compute or a fix) or a new
or a new command, it is **required** to include the corresponding command, it is **required** to include the **corresponding documentation**
documentation. Those are often new files that need to be added. in [reStructuredText format](https://docutils.sourceforge.io/rst.html).
In order to be included in the documentation, those new files Those are often new files that need to be added. In order to be
need to be reference in a `.. toctree::` block. Most of those included in the documentation, those new files need to be referenced in a
use patterns with wildcards, so the addition will be automatic. `.. toctree::` block. Most of those use patterns with wild cards, so the
However, those additions also need to be added to some lists of addition will be automatic. However, those additions also need to be
styles or commands. The `make style\_check` command will perform added to some lists of styles or commands. The `make style\_check`
a test and report any missing entries and list the affected files. command when executed in the `doc` folder will perform a test and report
Any references defined with `.. \_refname:` have to be unique any missing entries and list the affected files. Any references defined
across all documentation files and this can be checked for with with `.. \_refname:` have to be unique across all documentation files
`make anchor\_check`. Finally, a spell-check should be done, and this can be checked for with `make anchor\_check`. Finally, a
which is triggered via `make spelling`. Any offenses need to spell-check should be done, which is triggered via `make spelling`. Any
be corrected and false positives should be added to the file offenses need to be corrected and false positives should be added to the
`utils/sphinx-config/false\_positives.txt`. file `utils/sphinx-config/false\_positives.txt`.
## Required additional steps when adding a new package to LAMMPS ## Required additional steps when adding a new package to LAMMPS
TODO When adding a new package, the package must be added to the list of
packages in the `Packages_list.rst` file. If additional build instructions
need to be followed, a corresponding section should be added to the
`Build_extras.rst` file and linked from the list at the top of the
file as well as the equivalent list in the `Build_packages.rst` file.
A detailed description of the package and pointers to configuration,
included commands and examples, external pages, author information and
more should be added to the `Packages_details.rst` file.