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

[Michał Górny via Phabricator via llvm-commits]

mgorny created this revision.
mgorny added reviewers: JDevlieghere, sylvestre.ledru, mehdi_amini.
Herald added a project: LLVM.
mgorny added a comment.

(though personally I'd prefer just converting these three docs into .rst and having a single markup everywhere, without extra dependencies)


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.


https://reviews.llvm.org/D83161

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


Index: llvm/docs/conf.py
===================================================================
--- llvm/docs/conf.py
+++ 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'
 
Index: llvm/cmake/modules/AddSphinxTarget.cmake
===================================================================
--- llvm/cmake/modules/AddSphinxTarget.cmake
+++ llvm/cmake/modules/AddSphinxTarget.cmake
@@ -38,6 +38,7 @@
                             -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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D83161.275510.patch
Type: text/x-patch
Size: 1861 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20200704/f02fcc30/attachment.bin>