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"