[llvm] 446e3df - [llvm] [docs] Do not require recommonmark for manpage build

[Michał Górny via llvm-commits]

Author: Michał Górny
Date: 2020-07-07T20:59:02+02:00
New Revision: 446e3df25483312c8a7dfb3c53eef0de0e13074a

URL: https://github.com/llvm/llvm-project/commit/446e3df25483312c8a7dfb3c53eef0de0e13074a
DIFF: https://github.com/llvm/llvm-project/commit/446e3df25483312c8a7dfb3c53eef0de0e13074a.diff

LOG: [llvm] [docs] Do not require recommonmark for manpage build

Do not enforce recommonmark dependency if sphinx is called to build
manpages.  In order to do this, try to import recommonmark first
and do not configure it if it's not available.  Additionally, declare
a custom tags for the selected builder via CMake, and ignore
recommonmark import failure when 'man' target is used.

This will permit us to avoid the problematic recommonmark dependency
for the majority of Gentoo users that do not need to locally build
the complete documentation but want to have tool manpages.

Differential Revision: https://reviews.llvm.org/D83161

Added: 
    

Modified: 
    llvm/cmake/modules/AddSphinxTarget.cmake
    llvm/docs/conf.py

Removed: 
    


################################################################################
diff  --git a/llvm/cmake/modules/AddSphinxTarget.cmake b/llvm/cmake/modules/AddSphinxTarget.cmake
index f053d8084da4..b5babb30abcf 100644
--- a/llvm/cmake/modules/AddSphinxTarget.cmake
+++ b/llvm/cmake/modules/AddSphinxTarget.cmake
@@ -38,6 +38,7 @@ function (add_sphinx_target builder project)
                             -b ${builder}
                             -d "${SPHINX_DOC_TREE_DIR}"
                             -q # Quiet: no output other than errors and warnings.
+                            -t builder-${builder} # tag for builder
                             ${SPHINX_WARNINGS_AS_ERRORS_FLAG} # Treat warnings as errors if requested
                             "${ARG_SOURCE_DIR}" # Source
                             "${SPHINX_BUILD_DIR}" # Output

diff  --git a/llvm/docs/conf.py b/llvm/docs/conf.py
index 948c61c2c0f9..aed5e06b6f50 100644
--- a/llvm/docs/conf.py
+++ b/llvm/docs/conf.py
@@ -28,22 +28,29 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
 
-import sphinx
-if sphinx.version_info >= (3, 0):
-  # This requires 0.5 or later.
-  extensions.append('recommonmark')
-else:
-  source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = {
     '.rst': 'restructuredtext',
-    '.md': 'markdown',
 }
 
+try:
+  import recommonmark
+except ImportError:
+  # manpages do not use any .md sources
+  if not tags.has('builder-man'):
+    raise
+else:
+  import sphinx
+  if sphinx.version_info >= (3, 0):
+    # This requires 0.5 or later.
+    extensions.append('recommonmark')
+  else:
+    source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+  source_suffix['.md'] = 'markdown'
+
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'