Unverified Commit df8fb262 authored by Richard Berger's avatar Richard Berger
Browse files

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
parent 3f685c34

cmake/Modules/Documentation.cmake

+38 −47
Original line number Diff line number Diff line
@@ -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()

doc/.gitignore

+2 −0
Original line number Diff line number Diff line
@@ -15,3 +15,5 @@ 
/utils/sphinx-config/conf.py

/doxygen/Doxyfile

*.el

/utils/sphinx-config/_static/mathjax

/utils/sphinx-config/_static/polyfill.js

doc/Makefile

+2 −6
Original line number Diff line number Diff line
@@ -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 ;\

doc/utils/sphinx-config/conf.py.in

+11 −6
Original line number Diff line number Diff line
@@ -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',

CRA Git | Maintained and supported by SUSTech CRA and CCSE