Consolidate the redundant instructions for building the manual into one location.

doc/src/Build.rst

@@ -8,7 +8,7 @@ Makefiles, Ninja, Xcode, Visual Studio, KDevelop, CodeBlocks and more).
 
 As an alternative you can download a package with pre-built executables
 or automated build trees as described on the :doc:`Install <Install>`
-doc page.
+page.
 
 .. toctree::
    :maxdepth: 1
@@ -20,5 +20,6 @@ doc page.
    Build_settings
    Build_package
    Build_extras
+   Build_manual
    Build_windows
    Build_development

doc/src/Build_basics.rst

@@ -8,7 +8,6 @@ CMake and make:
 * :ref:`Choice of compiler and compile/link options <compile>`
 * :ref:`Build the LAMMPS executable and library <exe>`
 * :ref:`Including and removing debug support <debug>`
-* :ref:`Build the LAMMPS documentation <doc>`
 * :ref:`Install LAMMPS after a build <install>`
 
 ----------
@@ -466,69 +465,6 @@ the debug information from the LAMMPS executable:
 
 ----------
 
-.. _doc:
-
-Build the LAMMPS documentation
-----------------------------------------
-
-The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
-can be translated to different output format using the `Sphinx
-<sphinx_>`_ document generator tool.  Currently the translation to HTML
-and PDF (via LaTeX) are supported.  For that to work a Python 3
-interpreter and internet access is required.  For the documentation
-build a python based virtual environment is set up in the folder
-``doc/docenv`` and various python packages are installed into that
-virtual environment via the ``pip`` tool.  The actual translation is
-then done via ``make`` commands.
-
-.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
-.. _sphinx: https://www.sphinx-doc.org
-
-Documentation makefile options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following make commands can be issued in the doc folder of the
-LAMMPS source distribution.
-
-.. code-block:: bash
-
-  make html          # create HTML pages in html directory
-  make pdf           # create Manual.pdf in this directory
-  make fetch         # fetch HTML and PDF files from LAMMPS web site
-  make clean         # remove all intermediate files
-  make clean-all     # reset the entire doc build environment
-  make anchor_check  # scan for duplicate anchor labels
-  make style_check   # check for complete and consistent style lists
-  make package_check # check for complete and consistent package lists
-  make spelling      # spell-check the manual
-
-Thus "make html" will create a "doc/html" directory with the HTML format
-manual pages so that you can browse them with a web browser locally on
-your system.
-
-.. note::
-
-   You can also download a tarball of the documentation for the
-   current LAMMPS version (HTML and PDF files), from the website
-   `download page <https://lammps.sandia.gov/download.html>`_.
-
-CMake build options
-^^^^^^^^^^^^^^^^^^^
-
-It is also possible to create the HTML version (and only the HTML
-version) of the manual within the :doc:`CMake build directory
-<Build_cmake>`.  The reason for this option is to include the
-installation of the HTML manual pages into the "install" step when
-installing LAMMPS after the CMake build via ``make install``.  The
-documentation build is included in the default build target, but can
-also be requested independently with ``make doc``.
-
-.. code-block:: bash
-
-   -D BUILD_DOC=value       # yes or no (default)
-
-----------
-
 .. _tools:
 
 Build LAMMPS tools

doc/src/Build_manual.rst

@@ -1,5 +1,5 @@
-Building the LAMMPS manual
+Build the LAMMPS documentation
-**************************
+==============================
 
 Depending on how you obtained LAMMPS and whether you have built the
 manual yourself, this directory has a number of sub-directories and
@@ -39,23 +39,45 @@ a. You can "fetch" the current HTML and PDF files from the LAMMPS web
    will not, unless you update your local repository).
 
 b. You can build the HTML or PDF files yourself, by typing ``make html``
-   or ``make pdf``.  This requires various tools and files.  Some of them
+   or ``make pdf`` in the ``doc`` folder.  This requires various tools
-   have to be installed (more on that below). For the rest the build
+   and files.  Some of them have to be installed (see below).  For the
-   process will attempt to download and install them into a python
+   rest the build process will attempt to download and install them into
-   virtual environment and local folders.  This download is required
+   a python virtual environment and local folders.
-   only once, unless you type ``make clean-all``.  After that, viewing and
-   processing of the documentation can be done without internet access.
 
-A current version of the manual (latest patch release, aka unstable branch)
+A current version of the manual (latest patch release, aka unstable
-is is available online at: `https://lammps.sandia.gov/doc/Manual.html <https://lammps.sandia.gov/doc/Manual.html>`_
+branch) is is available online at:
-A version of the manual corresponding to the ongoing development
+`https://lammps.sandia.gov/doc/Manual.html
-(aka master branch) is available online at: `https://docs.lammps.org/ <https://docs.lammps.org/>`_
+<https://lammps.sandia.gov/doc/Manual.html>`_ A version of the manual
+corresponding to the ongoing development (aka master branch) is
+available online at: `https://docs.lammps.org/
+<https://docs.lammps.org/>`_
 
-----------
+Build using GNU make
+--------------------
 
-The generation of all documentation is managed by the Makefile in the
+The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
-doc directory. The following documentation related ``make`` commands are
+can be translated to different output format using the `Sphinx
-available:
+<sphinx_>`_ document generator tool.  It also incorporates programmer
+documentation extracted from the LAMMPS C++ sources through the `Doxygen
+<https://doxygen.nl>`_ program.  Currently the translation to HTML, PDF
+(via LaTeX), ePUB (for many e-book readers) and MOBI (for Amazon Kindle
+readers) are supported.  For that to work a Python 3 interpreter, the
+``doxygen`` tools and internet access to download additional files and
+tools are required.  This download is usually only required once or
+after the documentation folder is returned to a pristine state with
+``make clean-all``.
+
+.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
+.. _sphinx: https://www.sphinx-doc.org
+
+For the documentation build a python virtual environment is set up in
+the folder ``doc/docenv`` and various python packages are installed into
+that virtual environment via the ``pip`` tool.  For rendering embedded
+LaTeX code also the `MathJax <https://www.mathjax.org/>`_ and the
+`Polyfill <https://polyfill.io/>`_ JavaScript engines need to be downloaded.
+
+The actual translation is then done via ``make`` commands in the doc
+folder.  The following ``make`` commands are available:
 
 .. code-block:: bash
 
@@ -76,47 +98,60 @@ available:
 
 ----------
 
-Installing prerequisites for HTML build
+Build using CMake
-=======================================
+-----------------
+
+It is also possible to create the HTML version (and **only** the HTML
+version) of the manual within the :doc:`CMake build directory
+<Build_cmake>`.  The reason for this option is to include the
+installation of the HTML manual pages into the "install" step when
+installing LAMMPS after the CMake build via ``cmake --build . --target
+install``.  The documentation build is included in the default build
+target, but can also be requested independently with
+``cmake --build . --target doc``.
+
+.. code-block:: bash
+
+   -D BUILD_DOC=value       # yes or no (default)
+
+----------
+
+Prerequisites for HTML
+----------------------
 
 To run the HTML documentation build toolchain, python 3, git, doxygen,
 and virtualenv have to be installed locally.  Here are instructions for
 common setups:
 
-Ubuntu
+.. tabs::
-------
+
+   .. tab:: Ubuntu
 
       .. code-block:: bash
 
          sudo apt-get install python-virtualenv git doxygen
 
-Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x)
+   .. tab:: RHEL or CentOS (Version 7.x)
-------------------------------------------------------------------------------------
 
       .. code-block:: bash
 
          sudo yum install python3-virtualenv git doxygen
 
-Fedora (since version 22)
+   .. tab:: Fedora or RHEL/CentOS (8.x or later)
--------------------------
 
       .. code-block:: bash
 
          sudo dnf install python3-virtualenv git doxygen
 
-MacOS X
+   .. tab:: MacOS X
--------
 
-Python 3
+      *Python 3*
-^^^^^^^^
 
       Download the latest Python 3 MacOS X package from
-`https://www.python.org <https://www.python.org>`_
+      `https://www.python.org <https://www.python.org>`_ and install it.
-and install it.  This will install both Python 3
+      This will install both Python 3 and pip3.
-and pip3.
 
-virtualenv
+      *virtualenv*
-^^^^^^^^^^
 
       Once Python 3 is installed, open a Terminal and type
 
@@ -126,16 +161,16 @@ Once Python 3 is installed, open a Terminal and type
 
       This will install virtualenv from the Python Package Index.
 
-Installing prerequisites for PDF build
+Prerequisites for PDF
-======================================
+---------------------
 
 In addition to the tools needed for building the HTML format manual,
 a working LaTeX installation with support for PDFLaTeX and a selection
 of LaTeX styles/packages are required.  To run the PDFLaTeX translation
 the ``latexmk`` script needs to be installed as well.
 
-Installing prerequisites for e-book reader builds
+Prerequisites for ePUB and MOBI
-=================================================
+-------------------------------
 
 In addition to the tools needed for building the HTML format manual,
 a working LaTeX installation with a few add-on LaTeX packages
@@ -152,12 +187,12 @@ files, so you could download and view the PDF version as an alternative.
 
 
 Instructions for Developers
-===========================
+---------------------------
 
 When adding new styles or options to the LAMMPS code, corresponding
 documentation is required and either existing files in the ``src``
-folder need to be updated or new files added. These files are written
+folder need to be updated or new files added. These files are written in
-in `reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
+`reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
 
 Before contributing any documentation, please check that both the HTML
 and the PDF format documentation can translate without errors. Please also

doc/src/Manual.rst

@@ -19,10 +19,10 @@ all LAMMPS development is coordinated.
 
 ----------
 
-The content for this manual is part of the LAMMPS distribution.  You
+The content for this manual is part of the LAMMPS distribution.  You can
-can build a local copy of the Manual as HTML pages or a PDF file, by
+build a local copy of the Manual as HTML pages or a PDF file, by
-following the steps on the :doc:`Manual build <Manual_build>` page.
+following the steps on the :doc:`Build_manual` page.  The manual is
-The manual is organized in two parts:
+organized in two parts:
 1) the :ref:`User documentation <user_documentation>` for how to install
 and use LAMMPS and 2) the :ref:`Programmer documentation <programmer_documentation>`
 for how to write programs using the LAMMPS library from different
@@ -60,7 +60,6 @@ User Documentation
    Examples
    Tools
    Errors
-   Manual_build
 
 Programmer Documentation
 ************************