diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake index 99f570820a..feff66a9b2 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -9,9 +9,7 @@ if(BUILD_DOC) set(VIRTUALENV ${PYTHON_EXECUTABLE} -m virtualenv) - file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.txt) - file(GLOB PDF_EXTRA_SOURCES ${LAMMPS_DOC_DIR}/src/lammps_commands*.txt ${LAMMPS_DOC_DIR}/src/lammps_support.txt ${LAMMPS_DOC_DIR}/src/lammps_tutorials.txt) - list(REMOVE_ITEM DOC_SOURCES ${PDF_EXTRA_SOURCES}) + file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst) add_custom_command( OUTPUT docenv @@ -28,25 +26,10 @@ if(BUILD_DOC) COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters ) - set(RST_FILES "") - set(RST_DIR ${CMAKE_BINARY_DIR}/rst) - file(MAKE_DIRECTORY ${RST_DIR}) - foreach(TXT_FILE ${DOC_SOURCES}) - get_filename_component(FILENAME ${TXT_FILE} NAME_WE) - set(RST_FILE ${RST_DIR}/${FILENAME}.rst) - list(APPEND RST_FILES ${RST_FILE}) - add_custom_command( - OUTPUT ${RST_FILE} - DEPENDS requirements.txt docenv ${TXT_FILE} - COMMAND ${DOCENV_BINARY_DIR}/txt2rst -o ${RST_DIR} ${TXT_FILE} - ) - endforeach() - add_custom_command( OUTPUT html - DEPENDS ${RST_FILES} - COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src ${RST_DIR} - COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -j ${NPROCS} -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${RST_DIR} html + DEPENDS ${DOC_SOURCES} docenv requirements.txt + COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -j ${NPROCS} -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html ) add_custom_target( diff --git a/doc/README b/doc/README index 6db4ba3ca7..1416584eed 100644 --- a/doc/README +++ b/doc/README @@ -5,7 +5,7 @@ sub-directories and optionally 2 PDF files and an ePUB file: src content files for LAMMPS documentation html HTML version of the LAMMPS manual (see html/Manual.html) -tools tools and settings for building the documentation +utils utilities and settings for building the documentation Manual.pdf large PDF version of entire manual Developer.pdf small PDF with info about how LAMMPS is structured LAMMPS.epub Manual in ePUB format @@ -25,17 +25,12 @@ the fetched documentation will include those changes (but your source code will not, unless 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 -Sphinx, which the build process will attempt to download and install -on your system, if not already available. See more details below. - -(c) You can genererate an older, simpler, less-fancy style of HTML -documentation by typing "make old". This will create an "old" -directory. This can be useful if (b) does not work on your box for -some reason, or you want to quickly view the HTML version of a doc -page you have created or edited yourself within the src directory. -E.g. if you are planning to submit a new feature to LAMMPS. +html" or by "make pdf", respectively. This requires various tools +including the Python documentation processing tool Sphinx, which the +build process will attempt to download and install on your system into +a python virtual environment, if not already available. The PDF file +will require a working LaTeX installation with several add-on packages +in addition to the Python/Sphinx setup. See more details below. ---------------- @@ -46,11 +41,10 @@ Options: make html # generate HTML in html dir using Sphinx make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) - # in this dir via htmldoc and pdflatex -make old # generate old-style HTML pages in old dir via txt2html + # in this dir via Sphinx and PDFLaTeX make fetch # fetch HTML doc pages and 2 PDF files from web site # as a tarball and unpack into html dir and 2 PDFs -make epub # generate LAMMPS.epub in ePUB format using Sphinx +make epub # generate LAMMPS.epub in ePUB format using Sphinx make clean # remove intermediate RST files created by HTML build make clean-all # remove entire build folder and any cached data @@ -94,8 +88,17 @@ This will install virtualenv from the Python Package Index. Installing prerequisites for PDF build -[TBA] - +Same as for HTML plus a compatible LaTeX installation with +support for PDFLaTeX. Also the following LaTeX packages need +to be installed (e.g. from texlive): +- amsmath +- babel +- cmap +- fncychap +- geometry +- hyperref +- hypcap +- times ---------------- Installing prerequisites for epub build @@ -103,7 +106,11 @@ Installing prerequisites for epub build ## ePUB Same as for HTML. This uses the same tools and configuration -files as the HTML tree. +files as the HTML tree. The ePUB format conversion currently +does not support processing mathematical expressions via MathJAX, +so there will be limitations on some pages. For the time being +until this is resolved, building and using the PDF format file +is recommended instead. For converting the generated ePUB file to a mobi format file (for e-book readers like Kindle, that cannot read ePUB), you diff --git a/doc/lammps.1 b/doc/lammps.1 index ec31d19b74..a5045be5c4 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,4 +1,4 @@ -.TH LAMMPS "30 October 2019" "2019-10-30" +.TH LAMMPS "20 November 2019" "2019-11-20" .SH NAME .B LAMMPS \- Molecular Dynamics Simulator. diff --git a/doc/src/.gitignore b/doc/src/.gitignore index be126ab4aa..e0b9693457 100644 --- a/doc/src/.gitignore +++ b/doc/src/.gitignore @@ -1,2 +1,3 @@ -Eqs -JPG +/Eqs +/JPG +/false_positives.txt diff --git a/doc/src/Commands.rst b/doc/src/Commands.rst index e845faa903..f192d6a59d 100644 --- a/doc/src/Commands.rst +++ b/doc/src/Commands.rst @@ -27,8 +27,3 @@ commands in it are used to define a LAMMPS simulation. :maxdepth: 1 Commands_removed - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index 583e9e3c3a..d47c3299d0 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -1,59 +1,135 @@ -+----------------------------------------+------------------------------------+------------------------------------------+ -| :doc:`General commands ` | :doc:`Fix styles ` | :doc:`Compute styles ` | -+----------------------------------------+------------------------------------+------------------------------------------+ -| :doc:`Pair styles ` | :doc:`Bond styles ` | :ref:`Angle styles ` | -+----------------------------------------+------------------------------------+------------------------------------------+ -| :ref:`Dihedral styles ` | :ref:`Improper styles ` | :doc:`KSpace styles ` | -+----------------------------------------+------------------------------------+------------------------------------------+ +.. table_from_list:: + :columns: 3 + + * :doc:`General commands ` + * :doc:`Fix styles ` + * :doc:`Compute styles ` + * :doc:`Pair styles ` + * :ref:`Bond styles ` + * :ref:`Angle styles ` + * :ref:`Dihedral styles ` + * :ref:`Improper styles ` + * :doc:`KSpace styles ` General commands ================ An alphabetic list of all general LAMMPS commands. -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`angle\_coeff ` | :doc:`angle\_style ` | :doc:`atom\_modify ` | :doc:`atom\_style ` | :doc:`balance ` | :doc:`bond\_coeff ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`bond\_style ` | :doc:`bond\_write ` | :doc:`boundary ` | :doc:`box ` | :doc:`change\_box ` | :doc:`clear ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`comm\_modify ` | :doc:`comm\_style ` | :doc:`compute ` | :doc:`compute\_modify ` | :doc:`create\_atoms ` | :doc:`create\_bonds ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`create\_box ` | :doc:`delete\_atoms ` | :doc:`delete\_bonds ` | :doc:`dielectric ` | :doc:`dihedral\_coeff ` | :doc:`dihedral\_style ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`dimension ` | :doc:`displace\_atoms ` | :doc:`dump ` | :doc:`dump adios ` | :doc:`dump image ` | :doc:`dump movie ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`dump netcdf ` | :doc:`dump netcdf/mpiio ` | :doc:`dump vtk ` | :doc:`dump\_modify ` | :doc:`dynamical\_matrix ` | :doc:`echo ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`fix ` | :doc:`fix\_modify ` | :doc:`group ` | :doc:`group2ndx ` | :doc:`hyper ` | :doc:`if ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`info ` | :doc:`improper\_coeff ` | :doc:`improper\_style ` | :doc:`include ` | :doc:`jump ` | :doc:`kim\_init ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`kim\_interactions ` | :doc:`kim\_query ` | :doc:`kspace\_modify ` | :doc:`kspace\_style ` | :doc:`label