From df8fb26272086e727df778f3385a402242f1334d Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Tue, 25 Aug 2020 13:38:12 -0400 Subject: [PATCH] Refactor changes to documentation build - Added CMake variables for readability - Moved Mathjax files to _static to avoid special copy logic - Moved JPG/lammps-logo.png to _static to avoid special copy logic - Removed dead CMake code --- cmake/Modules/Documentation.cmake | 85 ++++++++---------- doc/.gitignore | 2 + doc/Makefile | 8 +- .../sphinx-config/_static}/lammps-logo.png | Bin doc/utils/sphinx-config/conf.py.in | 17 ++-- doc/utils/sphinx-config/lammps-logo.png | 1 - 6 files changed, 53 insertions(+), 60 deletions(-) rename doc/{src/JPG => utils/sphinx-config/_static}/lammps-logo.png (100%) delete mode 120000 doc/utils/sphinx-config/lammps-logo.png diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake index ddd284aa90..c3bf458cf5 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -19,62 +19,70 @@ if(BUILD_DOC) file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst) + add_custom_command( OUTPUT docenv COMMAND ${VIRTUALENV} docenv ) set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin) + set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt) + + set(SPHINX_CONFIG_DIR ${LAMMPS_DOC_DIR}/utils/sphinx-config) + set(SPHINX_CONFIG_FILE_TEMPLATE ${SPHINX_CONFIG_DIR}/conf.py.in) + set(SPHINX_STATIC_DIR ${SPHINX_CONFIG_DIR}/_static) + + # configuration and static files are copied to binary dir to avoid collisions with parallel builds + set(DOC_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc) + set(DOC_BUILD_CONFIG_FILE ${DOC_BUILD_DIR}/conf.py) + set(DOC_BUILD_STATIC_DIR ${DOC_BUILD_DIR}/_static) + set(DOXYGEN_BUILD_DIR ${DOC_BUILD_DIR}/doxygen) + set(DOXYGEN_XML_DIR ${DOXYGEN_BUILD_DIR}/xml) + + # copy entire configuration folder to doc build directory + # files in _static are automatically copied during sphinx-build, so no need to copy them individually + file(COPY ${SPHINX_CONFIG_DIR}/ DESTINATION ${DOC_BUILD_DIR}) + + # configure paths in conf.py, since relative paths change when file is copied + configure_file(${SPHINX_CONFIG_FILE_TEMPLATE} ${DOC_BUILD_CONFIG_FILE}) add_custom_command( - OUTPUT requirements.txt - DEPENDS docenv - COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt + OUTPUT ${DOC_BUILD_DIR}/requirements.txt + DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE} + COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt + COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters - COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r requirements.txt --upgrade + COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade ) # download mathjax distribution and unpack to folder "mathjax" - if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5) + if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5) file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.0.5.tar.gz" "${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz" EXPECTED_MD5 5d9d3799cce77a1a95eee6be04eb68e7) execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*) - execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${CMAKE_CURRENT_BINARY_DIR}/mathjax) + execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax) endif() - file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax) - file(COPY ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5 DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/) # for increased browser compatibility - if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js) + if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/polyfill.js) file(DOWNLOAD "https://polyfill.io/v3/polyfill.min.js?features=es6" - "${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js") + "${DOC_BUILD_STATIC_DIR}/polyfill.js") endif() # set up doxygen and add targets to run it - file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen) - set(DOXYGEN_XML_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen/xml) - add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen/lammps-logo.png - DEPENDS ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png - COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png ${CMAKE_BINARY_DIR}/doxygen/lammps-logo.png - ) - configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile) + file(MAKE_DIRECTORY ${DOXYGEN_BUILD_DIR}) + file(COPY ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png DESTINATION ${DOXYGEN_BUILD_DIR}/lammps-logo.png) + configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${DOXYGEN_BUILD_DIR}/Doxyfile) get_target_property(LAMMPS_SOURCES lammps SOURCES) - # need to update timestamps on pg_*.rst files after running doxygen to have sphinx re-read them - file(GLOB PG_SOURCES ${LAMMPS_DOC_DIR}/src/pg_*.rst) add_custom_command( OUTPUT ${DOXYGEN_XML_DIR}/index.xml DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES} - COMMAND Doxygen::doxygen ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen + COMMAND Doxygen::doxygen ${DOXYGEN_BUILD_DIR}/Doxyfile WORKING_DIRECTORY ${DOXYGEN_BUILD_DIR} COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp ) - # note, this may run in parallel with other tasks, so we must not use multiple processes here - file(COPY ${LAMMPS_DOC_DIR}/utils/sphinx-config DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/utils) - file(COPY ${LAMMPS_DOC_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) - configure_file(${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py) if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp) set(SPHINX_EXTRA_OPTS "-E") else() @@ -82,34 +90,17 @@ if(BUILD_DOC) endif() add_custom_command( OUTPUT html - DEPENDS ${DOC_SOURCES} docenv requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py - COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${CMAKE_BINARY_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html - COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${CMAKE_CURRENT_BINARY_DIR}/html/index.html + DEPENDS ${DOC_SOURCES} docenv ${DOC_BUILD_DIR}/requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE} + COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/html + COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${DOC_BUILD_DIR}/html/index.html COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp ) - # copy selected image files to html output tree - file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/_images/wsl_tutorial) - file(GLOB HTML_EXTRA_IMAGES RELATIVE ${LAMMPS_DOC_DIR}/src/img/ - ${LAMMPS_DOC_DIR}/src/img/[^.]*.jpg - ${LAMMPS_DOC_DIR}/src/img/[^.]*.gif - ${LAMMPS_DOC_DIR}/src/img/[^.]*.png - ${LAMMPS_DOC_DIR}/src/img/wsl_tutorial/[^.]*.png) - set(HTML_IMAGE_TARGETS "") - foreach(_IMG ${HTML_EXTRA_IMAGES}) - list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG}") - add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG} - DEPENDS ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/_images - COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_BINARY_DIR}/html/_images/${_IMG} - ) - endforeach() - add_custom_target( doc ALL - DEPENDS html ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/es5 ${HTML_IMAGE_TARGETS} + DEPENDS html ${DOC_BUILD_STATIC_DIR}/mathjax/es5 SOURCES ${LAMMPS_DOC_DIR}/utils/requirements.txt ${DOC_SOURCES} ) - install(DIRECTORY ${CMAKE_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) + install(DIRECTORY ${DOC_BUILD_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) endif() diff --git a/doc/.gitignore b/doc/.gitignore index 85c75c2934..7649fb34f1 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -15,3 +15,5 @@ /utils/sphinx-config/conf.py /doxygen/Doxyfile *.el +/utils/sphinx-config/_static/mathjax +/utils/sphinx-config/_static/polyfill.js diff --git a/doc/Makefile b/doc/Makefile index 1b5fb35b4c..7931525b92 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -4,11 +4,11 @@ SHELL = /bin/bash BUILDDIR = ${CURDIR} RSTDIR = $(BUILDDIR)/src VENV = $(BUILDDIR)/docenv -MATHJAX = $(BUILDDIR)/mathjax -POLYFILL = $(BUILDDIR)/mathjax/polyfill.js TXT2RST = $(VENV)/bin/txt2rst ANCHORCHECK = $(VENV)/bin/rst_anchor_check SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config +MATHJAX = $(SPHINXCONFIG)/_static/mathjax +POLYFILL = $(SPHINXCONFIG)/_static/polyfill.js PYTHON = $(shell which python3) DOXYGEN = $(shell which doxygen) @@ -106,9 +106,6 @@ html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) $(POLYFILL) @mkdir -p html/JPG @cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target: JPG' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/ @rm -rf html/PDF/.[sg]* - @mkdir -p html/_static/mathjax - @cp -r $(MATHJAX)/es5 html/_static/mathjax/ - @cp $(POLYFILL) html/_static/ @echo "Build finished. The HTML pages are in doc/html." spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt @@ -125,7 +122,6 @@ epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) @$(MAKE) $(MFLAGS) -C graphviz all @mkdir -p epub/JPG @rm -f LAMMPS.epub - @cp src/JPG/lammps-logo.png epub/ @cp src/JPG/*.* epub/JPG @(\ . $(VENV)/bin/activate ;\ diff --git a/doc/src/JPG/lammps-logo.png b/doc/utils/sphinx-config/_static/lammps-logo.png similarity index 100% rename from doc/src/JPG/lammps-logo.png rename to doc/utils/sphinx-config/_static/lammps-logo.png diff --git a/doc/utils/sphinx-config/conf.py.in b/doc/utils/sphinx-config/conf.py.in index 92ba10a341..c6b161ee14 100644 --- a/doc/utils/sphinx-config/conf.py.in +++ b/doc/utils/sphinx-config/conf.py.in @@ -23,11 +23,16 @@ try: except: pass +LAMMPS_DOC_DIR = '@LAMMPS_DOC_DIR@' +LAMMPS_SOURCE_DIR = '@LAMMPS_SOURCE_DIR@' +LAMMPS_PYTHON_DIR = '@LAMMPS_PYTHON_DIR@' +LAMMPS_DOXYGEN_XML_DIR = '@DOXYGEN_XML_DIR@' + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.insert(0, os.path.abspath('.')) -sys.path.append(os.path.join('@LAMMPS_DOC_DIR@', 'src', '_ext')) +sys.path.append(os.path.join(LAMMPS_DOC_DIR, 'src', '_ext')) # -- General configuration ------------------------------------------------ @@ -74,7 +79,7 @@ copyright = '2003-2020 Sandia Corporation' def get_lammps_version(): import os script_dir = os.path.dirname(os.path.realpath(__file__)) - with open(os.path.join('@LAMMPS_SOURCE_DIR@', 'version.h'), 'r') as f: + with open(os.path.join(LAMMPS_SOURCE_DIR, 'version.h'), 'r') as f: line = f.readline() start_pos = line.find('"')+1 end_pos = line.find('"', start_pos) @@ -167,7 +172,7 @@ html_title = "LAMMPS documentation" # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = 'lammps-logo.png' +html_logo = '_static/lammps-logo.png' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 @@ -328,7 +333,7 @@ texinfo_documents = [ epub_title = 'LAMMPS Documentation - ' + get_lammps_version() -epub_cover = ('lammps-logo.png', '') +epub_cover = ('_static/lammps-logo.png', '') epub_description = """ This is the Manual for the LAMMPS software package. @@ -363,7 +368,7 @@ from sphinx.highlighting import lexers lexers['LAMMPS'] = LAMMPSLexer.LAMMPSLexer(startinline=True) -sys.path.append('@LAMMPS_PYTHON_DIR@') +sys.path.append(LAMMPS_PYTHON_DIR) # avoid syntax highlighting in blocks that don't specify language highlight_language = 'none' @@ -375,7 +380,7 @@ autodoc_member_order = 'bysource' # breathe configuration -breathe_projects = { 'progguide' : '@DOXYGEN_XML_DIR@' } +breathe_projects = { 'progguide' : LAMMPS_DOXYGEN_XML_DIR } breathe_default_project = 'progguide' breathe_show_define_initializer = True breathe_domain_by_extension = { 'h' : 'cpp', diff --git a/doc/utils/sphinx-config/lammps-logo.png b/doc/utils/sphinx-config/lammps-logo.png deleted file mode 120000 index 37d35bece1..0000000000 --- a/doc/utils/sphinx-config/lammps-logo.png +++ /dev/null @@ -1 +0,0 @@ -../../src/JPG/lammps-logo.png \ No newline at end of file