tx258/lammps-gran-kokkos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation for new "make fasthtml"

Browse Source
This commit is contained in:
Axel Kohlmeyer
2025-03-12 17:50:27 -04:00
parent c7f5d07a68
commit 130b898e26
2 changed files with 36 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
doc/src/Build_manual.rst
View File

@ -78,8 +78,7 @@ folder. The following ``make`` commands are available:
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert
make fasthtml # generate approximate HTML in fasthtml dir using Sphinx
# some Sphinx extensions do not work correctly with this
make fasthtml # generate approximate HTML in fasthtml dir using pandoc
make clean # remove intermediate RST files created by HTML build
make clean-all # remove entire build folder and any cached data
@ -205,12 +204,41 @@ documentation is required and either existing files in the ``src``
folder need to be updated or new files added. These files are written in
`reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
Testing your contribution
^^^^^^^^^^^^^^^^^^^^^^^^^
Before contributing any documentation, please check that both the HTML
and the PDF format documentation can translate without errors. During
testing the html translation, you may use the ``make fasthtml`` command
which does an approximate translation (i.e. not all Sphinx features and
extensions will work), but runs very fast because it will only translate
files that have been changed since the last ``make fasthtml`` command.
and the PDF format documentation can translate without errors and that
there are no spelling issues. This is done with ``make html``, ``make pdf``,
and ``make spelling``, respectively.
Fast and approximate translation to HTML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Translating the full manual to HTML or PDF can take a long time. Thus
there is a fast and approximate way to translate the reStructuredText to
HTML as a quick-n-dirty way of checking your manual page.
This translation uses `Pandoc <https://pandoc.org>`_ instead of Sphinx
and thus all special Sphinx features (cross-references, advanced tables,
embedding of Python docstring and doxygen documentation, and so on) will
not render correctly. But this is a **very fast** way to check the content
as HTML while writing the documentation.
To translate **all** manual pages, you can type ``make fasthtml`` at the
command line. The translated HTML files are then in the ``fasthtml``
folder All following ``make fasthtml`` commands will only translate
``.rst`` files that have been changed. The ``make fasthtml`` command
can be parallelized with make using the `-j` flag. You can also
directly translate only individual pages: e.g. to translate only the
``doc/src/pair_lj.rst`` page type ``make fasthtml/pair_lj.html``
After writing the documentation is completed, you will still need
to verify with ``make html`` and ``make pdf`` that it translates
correctly.
Tests for consistency, completeness, and other known issues
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please also check the output to the console for any warnings or problems. There will
be multiple tests run automatically:

2
doc/src/pair_lj.rst
View File

@ -68,7 +68,7 @@ LJ cutoff specified in the pair_style command is used.
Note that :math:`\sigma` is defined in the LJ formula as the
zero-crossing distance for the potential, *not* as the energy minimum at
:math:`r_0 = 2^{\frac{1}{6}} \sigma`. The _same_ potential function becomes:
:math:`r_0 = 2^{\frac{1}{6}} \sigma`. The *same* potential function becomes:
.. math::