Minor Sphinx documentation generation improvements

[t-tye]

Summary

Minor improvements to documentation for generating Sphinx documentation.

Minor improvements to CMake to generate Sphinx documentation.

[MaskRay]

lld/docs/sphinx_intro.rst

44

easy_install is deprecated https://packaging.python.org/discussions/pip-vs-easy-install/

We should just remove mention of it.

[t-tye]

Remove mention of easy_install as deprecated. MacOS still appears to only come with easy_install.

[t-tye]

lld/docs/sphinx_intro.rst

44

Updated as suggested. MacOS still appears to use easy_install.

[scott.linder]

LGTM, as long as @MaskRay is satisfied with the changes around easy_install. If MacOS still uses it but we want to discourage it on Linux then I like the current wording.

llvm/docs/CMakeLists.txt

162

Could the above comment be replaced with the trailing "Slash indicates contents of" comment?

[t-tye]

Replaced comment with a trailing "Slash indicates contents of" comment as suggested by @scott.linder.

[t-tye]

llvm/docs/CMakeLists.txt

162

Made change as suggested. This is now consistent with the other places that do the same thing.

lld/docs/sphinx_intro.rst

installation tool ``easy_install``, as follows::
   Reading http://pypi.python.org/simple/sphinx/
   Reading http://sphinx.pocoo.org/
   Best match: Sphinx 1.1.3
   ... more lines here ..
 
 If you do not have root access (or otherwise want to avoid installing Sphinx in
 system directories) see the section on :ref:`installing_sphinx_in_a_venv` .
 
-If you do not have the ``easy_install`` tool on your system, you should be able
-to install it using:
+If you do not have the ``pip`` or ``easy_install`` tool on your system, you
+should be able to install it using:
 
   Linux
     Use your distribution's standard package management tool to install it,
-    i.e., ``apt-get install easy_install`` or ``yum install easy_install``.
+    i.e., ``apt-get install python3-pip`` or ``yum install python3-pip``.
 
   macOS
     All modern macOS systems come with ``easy_install`` as part of the base
     system.
 
   Windows
     See the `setuptools <http://pypi.python.org/pypi/setuptools>`_ package web
     page for instructions.
 
 
 .. _building_the_documentation:
 
 Building the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to build the documentation need to add ``-DLLVM_ENABLE_SPHINX=ON`` to
 your ``cmake`` command.  Once you do this you can build the docs using
 ``docs-lld-html`` build (``ninja`` or ``make``) target.
 
 That build target will invoke ``sphinx-build`` with the appropriate options for
 the project, and generate the HTML documentation in a ``tools/lld/docs/html``
 subdirectory.

llvm/cmake/modules/AddSphinxTarget.cmake

if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
       if (builder STREQUAL man)
         # FIXME: We might not ship all the tools that these man pages describe
         install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
                 COMPONENT "${project}-sphinx-man"
                 DESTINATION "${CMAKE_INSTALL_MANDIR}/man1")
 
         if(NOT LLVM_ENABLE_IDE)
           add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
-                                   DEPENDS ${SPHINX_TARGET_NAME}
+                                   DEPENDS "${SPHINX_TARGET_NAME}"
                                    COMPONENT "${project}-sphinx-man")
         endif()
       elseif (builder STREQUAL html)
         string(TOUPPER "${project}" project_upper)
         set(${project_upper}_INSTALL_SPHINX_HTML_DIR "${CMAKE_INSTALL_DATADIR}/doc/${project}/html"
             CACHE STRING "HTML documentation install directory for ${project}")
 
-        # '/.' indicates: copy the contents of the directory directly into
-        # the specified destination, without recreating the last component
-        # of ${SPHINX_BUILD_DIR} implicitly.
-        install(DIRECTORY "${SPHINX_BUILD_DIR}/."
+        install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
                 COMPONENT "${project}-sphinx-html"
-                DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
+                DESTINATION "$CACHE{${project_upper}_INSTALL_SPHINX_HTML_DIR}")
 
         if(NOT LLVM_ENABLE_IDE)
           add_llvm_install_targets("install-${SPHINX_TARGET_NAME}"
                                    DEPENDS ${SPHINX_TARGET_NAME}
                                    COMPONENT "${project}-sphinx-html")
         endif()
       else()
         message(WARNING Installation of ${builder} not supported)
       endif()
     endif()
   endif()
 endfunction()

llvm/docs/CMakeLists.txt

add_custom_target(ocaml_doc
     COMMAND ${OCAMLFIND} ocamldoc -d ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html
                                   -sort -colorize-code -html ${odoc_files}
     COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/_ocamldoc/style.css
                                      ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html)
 
   add_dependencies(ocaml_doc ${doc_targets})
 
   if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
-    # ./ suffix is needed to copy the contents of html directory without
-    # appending html/ into LLVM_INSTALL_OCAMLDOC_HTML_DIR.
-    install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html/.
+    install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html/" # Slash indicates contents of
       COMPONENT ocamldoc-html
       DESTINATION "${LLVM_INSTALL_OCAMLDOC_HTML_DIR}")
   endif()
 endif()

llvm/docs/README.txt

 LLVM Documentation
 ==================
 
 LLVM's documentation is written in reStructuredText, a lightweight
 plaintext markup language (file extension `.rst`). While the
 reStructuredText documentation should be quite readable in source form, it
 is mostly meant to be processed by the Sphinx documentation generation
 system to create HTML pages which are hosted on <https://llvm.org/docs/> and
 updated after every commit. Manpage output is also supported, see below.
 
 If you instead would like to generate and view the HTML locally, install
 Sphinx <http://sphinx-doc.org/> and then do:
 
     cd <build-dir>
     cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
     make -j3 docs-llvm-html
-    $BROWSER <build-dir>/docs//html/index.html
+    $BROWSER <build-dir>/docs/html/index.html
 
-The mapping between reStructuredText files and generated documentation is
-`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `https://llvm.org/docs/Foo.html`.
+The correspondence between reStructuredText files and generated HTML pages is:
+
+LLVM project
+    `llvm/docs/Foo.rst` <-> `<build-dir>/docs/html/Foo.html` <-> `<install-dir>/share/doc/llvm/html/Foo.html` <-> `https://llvm.org/docs/Foo.html`
+
+Other projects
+    `<project>/docs/Foo.rst` <-> `<build-dir>/tools/<project>/docs/html/Foo.html` <-> `<install-dir>/share/doc/<project>/html/Foo.html`<-> `https://<project>.llvm.org/docs/Foo.html`
 
 If you are interested in writing new documentation, you will want to read
 `SphinxQuickstartTemplate.rst` which will get you writing documentation
 very fast and includes examples of the most important reStructuredText
 markup syntax.
 
 Manpage Output
-===============
+==============
 
 Building the manpages is similar to building the HTML documentation. The
 primary difference is to use the `man` makefile target, instead of the
 default (which is `html`). Sphinx then produces the man pages in the
 directory `<build-dir>/docs/man/`.
 
     cd <build-dir>
     cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
     make -j3 docs-llvm-man
-    man -l >build-dir>/docs/man/FileCheck.1
+    man -l <build-dir>/docs/man/FileCheck.1
+
+The correspondence between reStructuredText files and generated man pages is:
+
+LLVM project
+    `llvm/docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
+
+Other projects
+    `<project>/docs/CommandGuide/Foo.rst` <-> `<build-dir>/tools/<project>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
 
-The correspondence between .rst files and man pages is
-`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
 These .rst files are also included during HTML generation so they are also
-viewable online (as noted above) at e.g.
-`https://llvm.org/docs/CommandGuide/Foo.html`.
+viewable online:
+
+LLVM project
+    `https://llvm.org/docs/CommandGuide/Foo.html`
+
+Other projects
+    `https://<project>.llvm.org/docs/CommandGuide/Foo.html`
 
 Checking links
 ==============
 
 The reachability of external links in the documentation can be checked by
 running:
 
     cd docs/
     make -f Makefile.sphinx linkcheck
 
 Doxygen page Output
-==============
+===================
 
 Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.
 
     cd <build-dir>
     cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
     make doxygen-llvm # for LLVM docs
     make doxygen-clang # for clang docs
 
 It will generate html in
 
     <build-dir>/docs/doxygen/html # for LLVM docs
     <build-dir>/tools/clang/docs/doxygen/html # for clang docs

openmp/docs/README.txt

 OpenMP LLVM Documentation
-==================
+=========================
 
 OpenMP LLVM's documentation is written in reStructuredText, a lightweight
 plaintext markup language (file extension `.rst`). While the
 reStructuredText documentation should be quite readable in source form, it
 is mostly meant to be processed by the Sphinx documentation generation
 system to create HTML pages which are hosted on <https://llvm.org/docs/> and
 updated after every commit. Manpage output is also supported, see below.
 
 If you instead would like to generate and view the HTML locally, install
 Sphinx <http://sphinx-doc.org/> and then do:
 
     cd <build-dir>
     cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
     make
-    $BROWSER <build-dir>/projects/openmp/docs//html/index.html
+    $BROWSER <build-dir>/projects/openmp/docs/html/index.html
 
-The mapping between reStructuredText files and generated documentation is
-`docs/Foo.rst` <-> `<build-dir>/projects/openmp/docs//html/Foo.html` <->
-`https://openmp.llvm.org/docs/Foo.html`.
+The correspondence between reStructuredText files and generated HTML pages is:
+
+LLVM project
+    `llvm/docs/Foo.rst` <-> `<build-dir>/docs/html/Foo.html` <-> `<install-dir>/share/doc/llvm/html/Foo.html` <-> `https://llvm.org/docs/Foo.html`
+
+Other projects (such as openmp)
+    `<project>/docs/Foo.rst` <-> `<build-dir>/tools/<project>/docs/html/Foo.html` <-> `<install-dir>/share/doc/<project>/html/Foo.html`<-> `https://<project>.llvm.org/docs/Foo.html`
 
 If you are interested in writing new documentation, you will want to read
 `llvm/docs/SphinxQuickstartTemplate.rst` which will get you writing
 documentation very fast and includes examples of the most important
 reStructuredText markup syntax.
 
 Manpage Output
-===============
+==============
 
 Building the manpages is similar to building the HTML documentation. The
 primary difference is to use the `man` makefile target, instead of the
 default (which is `html`). Sphinx then produces the man pages in the
 directory `<build-dir>/docs/man/`.
 
     cd <build-dir>
     cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
     make
-    man -l >build-dir>/docs/man/FileCheck.1
+    man -l <build-dir>/tools/openmp/docs/man/openmp.1
+
+The correspondence between reStructuredText files and generated man pages is:
+
+LLVM project
+    `llvm/docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
+
+Other projects (such as openmp)
+    `<project>/docs/CommandGuide/Foo.rst` <-> `<build-dir>/tools/<project>/docs/man/Foo.1` <-> `<install-dir>/share/man/man1/Foo.1`
 
-The correspondence between .rst files and man pages is
-`docs/CommandGuide/Foo.rst` <-> `<build-dir>/projects/openmp/docs//man/Foo.1`.
 These .rst files are also included during HTML generation so they are also
-viewable online (as noted above) at e.g.
-`https://openmp.llvm.org/docs/CommandGuide/Foo.html`.
+viewable online:
+
+LLVM project
+    `https://openmp.llvm.org/docs/CommandGuide/Foo.html`
+
+Other projects (such as openmp)
+    `https://<project>.llvm.org/docs/CommandGuide/Foo.html`