Make man pages SEE ALSO by convention. Improve docs building.

docs/man/Makefile

@@ -5,7 +5,9 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = ../dist
+# for cache, etc.
+_BUILDDIR     = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -15,7 +17,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(_BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -52,6 +54,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(_BUILDDIR)/*
 
 .PHONY: html
 html:

docs/man/cdist-install.rst

@@ -76,9 +76,9 @@ If you want to build and use the manpages, run:
 .. code-block:: sh
 
     make man
-    export MANPATH=$MANPATH:$(pwd -P)/docs/man/_build/man
+    export MANPATH=$MANPATH:$(pwd -P)/docs/dist/man
 
-Or you can move manpages from docs/man/_build/man directory to some
+Or you can move manpages from docs/dist/man directory to some
 other directory and add it to MANPATH.
 
 You can also build manpages for types in your ~/.cdist directory:
@@ -87,12 +87,23 @@ You can also build manpages for types in your ~/.cdist directory:
 
     make dotman
 
-Built manpages are now in docs/man/_build/man directory. If you have
-some other custom .cdist directory, e.g. /custom/.cdist then use:
+Built manpages are now in docs/dist/man directory. If you have
+some other custom .cdist directory, e.g. /opt/cdist then use:
 
 .. code-block:: sh
 
-    DOT_CDIST_PATH=/custom/.cdist make dotman
+    DOT_CDIST_PATH=/opt/cdist make dotman
+
+Building and using HTML documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to build and use HTML documentation, run:
+
+.. code-block:: sh
+
+    make html
+
+Now you can access docs/dist/html/index.html.
 
 Python package
 ~~~~~~~~~~~~~~

docs/man/conf.py

@@ -310,9 +310,3 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
-
-extlinks = {
-    'cdist_docs':
-        ('http://www.nico.schottelius.org/software/cdist/man/{}/%s.html'.format(
-            release), None),
-}

docs/man/man1/cdist.rst

@@ -175,10 +175,6 @@ The following exit values shall be returned:
     One or more host configurations failed
 
 
-SEE ALSO
---------
-Full documentation at: <:cdist_docs:`index`>.
-
 AUTHORS
 -------
 Nico Schottelius <nico-cdist--@--schottelius.org>