ADD: generate man page by default and set install

Generate and install the man page, using docs/usage.rst by default. In
order to generate the doc site, it is necessary to setup meson with the
options '-Dsphinx_target=html' and, in that case, the extension
sphinx_rtd_theme will be mandatory.

.readthedocs.yml

@@ -12,6 +12,7 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
+  builder: html
   configuration: docs/conf.py
 
 # Optional but recommended, declare the Python requirements required

docs/conf.py

@@ -12,11 +12,13 @@
 # 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.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-import sphinx_rtd_theme
+import os
+import sys
 
+sys.path.insert(0, os.path.abspath('.'))
+
+if 'html' in sys.argv:
+    import sphinx_rtd_theme
 
 # -- Project information -----------------------------------------------------
 
@@ -53,6 +55,11 @@
 # The master toctree document.
 master_doc = 'index'
 
+# Change the master toctree document for man page
+if 'man' in sys.argv:
+    extensions.remove('sphinx_rtd_theme')
+    master_doc = 'usage'
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -142,7 +149,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'sideretro', u'sideRETRO Documentation',
+    (master_doc, 'sider', u'sideRETRO Documentation',
      [author], 1)
 ]
 

docs/meson.build

@@ -31,16 +31,42 @@ doc_images = files(
 )
 
 sphinx_source_dir = join_paths(meson.source_root(), 'docs')
-sphinx_builddir   = join_paths(meson.build_root(), 'meson-docs')
+sphinx_builddir   = join_paths(meson.build_root(),  'docs')
 
 # Test if sphinx is installed
 if sphinx_build.found()
-  custom_target('docs',
-      input : [doc_sources, doc_images],
-     output : ['.'],
-    command : [sphinx_build, '-M', get_option('sphinx_target'),
-      sphinx_source_dir, sphinx_builddir]
-  )
+  sphinx_target = get_option('sphinx_target')
+
+  sphinx_cmd = [
+    sphinx_build,
+    '-b', sphinx_target,
+    sphinx_source_dir,
+    sphinx_builddir
+  ]
+
+  # If the user passed the option '-Dsphinx_target=man', then
+  # we build a man page and set the installation to
+  # /usr/local/man/man1
+  if sphinx_target == 'man'
+    message('Generate man page alongside the executable')
+
+    custom_target('docs',
+                 input : [doc_sources, doc_images],
+                output : ['sider.1'],
+               install : true,
+      build_by_default : true,
+           install_dir : join_paths('man', 'man1'),
+               command : sphinx_cmd
+    )
+  else
+    custom_target('docs',
+                 input : [doc_sources, doc_images],
+                output : ['.'],
+               install : false,
+      build_by_default : false,
+               command : sphinx_cmd
+    )
+  endif
 else
   # Make users aware that without sphinx the documentation
   # cannot be generated

meson_options.txt

@@ -1,6 +1,6 @@
 option('sphinx_target',
      type : 'combo',
-    value : 'html',
+    value : 'man',
   choices : [
     'html',
     'dirhtml',