Document documentation

doc/documentation.md

@@ -0,0 +1,69 @@
+LinkChecker Documentation
+=========================
+
+LinkChecker is documented with man pages and HTML that is used for the project web site.
+Both are generated using Sphinx, with Makefiles provided to simplify the process.
+
+Sources are found in doc/src. Stand-alone .rst files from doc/ are also included.
+
+In addition to Sphinx the dependencies for building the documentation are:
+
+graphviz
+
+sphinx_epytext
+
+sphinx_rtd_theme
+
+
+Man Pages
+---------
+
+Source files are in doc/src/man.
+
+The pages can be built with:
+
+``linkchecker/doc $ make man``
+
+The files are saved in doc/man.
+
+See translations.md for information about creating localised man pages.
+
+Published man pages are included in the LinkChecker repository.
+
+
+HTML
+----
+
+``doc/src/code/index.rst`` gives an overview of the LinkChecker code, optionally a navigable
+copy of the LinkChecker source can be created with:
+
+``linkchecker/doc $ make code``
+
+Build the HTML files with:
+
+``linkchecker/doc $ make html``
+
+The files are saved in doc/html.
+
+
+Publishing the Web Site
+-----------------------
+
+The Web Site is hosted by GitHub Pages from the docs/ directory of the gh-pages branch.
+
+/docs is a fixed GitHub pages location and contains ``.nojekyll``.
+
+To create a topic branch with updated documentation suitable for a PR:
+
+    git checkout master
+
+    ./setup.py build  # for copyright, author and version info
+    make -C doc code
+    make -C doc html
+
+    git checkout -b <branch> gh-pages
+
+    rm -rf docs/*
+    cp -a doc/html/* docs/
+
+    git commit -a -m "Update documentation"