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

[mgorny]

Summary

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.

[mgorny]

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

[JDevlieghere]

I think this makes sense, I often need to build just the man pages and if we can avoid the dependency I'm all for it. LGTM.

In D83161#2131468, @mgorny wrote:

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

Personally I agree, but it seems LLVM might be moving in the opposite direction.

llvm/cmake/modules/AddSphinxTarget.cmake

if (NOT ARG_SOURCE_DIR)
     set(ARG_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
   endif()
 
   add_custom_target(${SPHINX_TARGET_NAME}
                     COMMAND ${SPHINX_EXECUTABLE}
                             -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
                     COMMENT
                     "Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
 
   # When "clean" target is run, remove the Sphinx build directory
   set_property(DIRECTORY APPEND PROPERTY

llvm/docs/conf.py

 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # 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'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
 project = u'LLVM'