.. _Setting up a Sphinx Server: ######################################## RST Workshop: Setting up a Sphinx Server ######################################## .. note:: This guide serves two purposes: #. It is **the result of** part 1, :ref:`Writing in RST - Overview`. #. It serves as a basic guide to configuring Sphinx on a server. .. contents:: Table of Contents Overview ============ **Sphinx** is a platform that *renders RST files* to a web application that is suitable for documentation. This guide provides a quick installation guide for someone wanting to set up Sphinx on a VSP. The `install sphinx guide `_ provides a good starting point, but we will make other changes to install the latest version of Sphinx from PyPI. The VPS setup for this workshop uses Docker image `nginx:latest `_, which uses Debian 10. Installing Sphinx ================= The `Sphinx documentation `_ provides instructions for Debian/Ubuntu (apt), RHEL/CentOS (yum), and MacOS (homebrew). This guide will uses the ``apt`` package manager.. Unfortunately, the apt package manager for Debian has an old version of Sphinx (Sphinx 1.8.4). It works, but PyPI has the `latest version of Sphinx `_. Therefore, this guide shows to install Sphinx using both ``apt`` and ``pip3``. .. note:: Other distributions are supported using pip, such as Alpine Linux. However, additional knowledge is required to install prerequisites for specific Python packages. Spin up a VPS with your favorite Linux distro --------------------------------------------- This workshop uses a simple ``docker-compose.yml`` file to start the instance and then uses Nginx on the host as a reverse proxy. You can view the :ref:`Sphinx Docker Environment`. Install Sphinx using the package manager ---------------------------------------- You can choose to install the Sphinx version (1.7.x) using the apt package manager or you install the latest version (2.x) using from PyPI using. .. caution:: Installing both versions could result in a conflict. #. Update your repository and upgrade any out-of-date packages using ``apt-get update && apt upgrade``. #. Install a version of Sphinx: - Sphinx version 1.x a. Install Sphinx version 1: ``apt-get -y install python3-sphinx`` - Sphinx version 2.x a. Install pip3: ``apt-get -y install python3-pip`` b. Install Sphinx version 2: ``pip3 install Sphinx`` Configure Sphinx using ``sphinx-quickstart`` ============================================ You need to configure Sphinx the first time you use it. Sphinx provides a quickstart tool! .. important:: Create and then change to the directory of your Sphinx code and RST content. The default installation directory is ``./``, which is the **current directory**. #. Create a project folder, then navigate to that folder * For example: ``mkdir -p /opt/sphinx && cd /opt/sphinx`` #. Execute command ``sphinx-quickstart`` #. Follow the prompts (from version 1.x) We've highlighted the lines that we entered a value *other than* default. Add the extensions that you find useful. .. code-block:: bash :caption: Output of 'sphinx-quickstart' for v.1 :linenos: :emphasize-lines: 9,10,34,39,46 > Separate source and build directories (y/n) [n]: Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: Conference Demo > Author name(s): BilimEdtech > Project release []: If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. > Project language [en]: The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: Indicate which of the following Sphinx extensions should be enabled: > autodoc: automatically insert docstrings from modules (y/n) [n]: > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y > coverage: checks for documentation coverage (y/n) [n]: > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: y > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html` instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]: n .. note:: * The configurations for your Sphinx project are in file ``conf.py``. * Delete file ``conf.py`` to run the quickstart again. Rendering to HTML ================= We can configure Sphinx to *auto-build* the output when it detects a change, or we can initiate a manual build. The command to generate output is ``make ``. Sphinx can convert RST to various formats. You can run the ``make command`` without any args to view the possible output types. .. code-block:: bash root@26f88a20b58c:/opt/sphinx# make Sphinx v2.3.1 Please use `make target` where target is one of html to make standalone HTML files dirhtml to make HTML files named index.html in directories singlehtml to make a single large HTML file pickle to make pickle files json to make JSON files htmlhelp to make HTML files and an HTML help project qthelp to make HTML files and a qthelp project devhelp to make HTML files and a Devhelp project epub to make an epub latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter latexpdf to make LaTeX and PDF files (default pdflatex) latexpdfja to make LaTeX files and run them through platex/dvipdfmx text to make text files man to make manual pages texinfo to make Texinfo files info to make Texinfo files and run them through makeinfo gettext to make PO message catalogs changes to make an overview of all changed/added/deprecated items xml to make Docutils-native XML files pseudoxml to make pseudoxml-XML files for display purposes linkcheck to check all external links for integrity doctest to run all doctests embedded in the documentation (if enabled) coverage to run coverage check of the documentation (if enabled) Our desired output is HTML. #. Build the HTML by executing command ``make html`` .. code-block:: bash root@1a40c1841674:/opt/sphinx# make html Running Sphinx v2.3.1 making output directory... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: [new config] 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindexdone writing additional pages... searchdone copying static files... ... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded. #. Navigate to the URL of the Sphinx instance to view rendered HTML. |default-sphinx| Adding Content ============== .. note:: All of the RST contents and settings are in the root of the Sphinx directory. Default index.html ------------------ Executing ``make html`` on a default project creates an ``index.html`` in the root folder of the project using the parameters from ``conf.py``. .. code-block:: rst :caption: Default 'index.rst' file .. Demo documentation master file, created by sphinx-quickstart on Sun Dec 29 06:49:53 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Demo's documentation! ================================ .. toctree:: :maxdepth: 2 :caption: Contents: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` Create Folders -------------- Sphinx makes it easy to organize content in folders. #. Create a folder, such as ``web-guide``. #. Create a file ``web-guide/index.rst`` with the following content: .. code-block:: rst :caption: web-guide/index.rst contents ******************* Project X Web Guide ******************* This guide provides the documentation for our web frontend. #. Now, link to the ``web-guide/index.rst`` by placing the path in the root ``index.rst``. .. code-block:: rst :caption: ./index.rst contents :linenos: :emphasize-lines: 13 .. Demo documentation master file, created by sphinx-quickstart on Sun Dec 29 06:49:53 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Demo's documentation! ================================ .. toctree:: :maxdepth: 2 :caption: Contents: web-guide/index . . . #. Build the HTML and then refresh the page. The page should show up in the left navigation panel and on the home page. Pay close attention to the number of spaces, which should be exactly three. A wrong indentation level will result in an error similar to: .. code-block:: bash :linenos: :emphasize-lines: 7,8,11,12 Running Sphinx v2.3.1 loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] index /opt/sphinx/index.rst:9: WARNING: toctree contains reference to nonexisting document ' web-guide/index' looking for now-outdated files... none found pickling environment... done checking consistency... /opt/sphinx/web-guide/index.rst: WARNING: document isn’t included in any toctree done preparing documents... done writing output... [100%] index generating indices... genindexdone done copying static files... ... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded, 2 warnings. The HTML pages are in _build/html. Install a Different Theme ========================= Sphinx generates HTML, CSS, JS and support code using the `Alabaster `_ theme by default. Sphinx has ample `support for themes `_. Write the Docs recommends these `top four themes `_. - `Read the Docs Theme `_ - `Alabaster `_ - `Sphinx Bootstrap Theme `_ - `Guzzle Theme `_ Install Read the Docs Theme --------------------------- `Read the Docs Theme `_ is a popular theme for Sphinx. `PyPI hosts `_ Read the Docs theme. #. Install ``pip3`` if you do not install it earlier: ``apt-get -y install python3-pip`` #. Install ``sphinx-rtd-theme`` using pip3: ``pip3 install sphinx-rtd-theme`` #. Edit your ``conf.py`` file and make the following modifications: .. code-block:: python :caption: conf.py import sphinx_rtd_theme extensions = [ ... 'sphinx_rtd_theme', ] # html_theme = 'alabaster' html_theme = "sphinx_rtd_theme" #. Rebuild the HTML to display the new theme. You can rebuild the HTML in the container from the host using ``docker exec``. .. code-block:: bash # Using docker-compose docker-compose exec sphinx bash -c "cd /opt/sphinx && make html" # Using docker docker exec -t sphinx_nginx bash -c "cd /opt/sphinx && make html" |rtd-theme| .. hint:: Sometimes the HTML in folder ``_build`` contains old data, especially if you remove or rename a file. To solve this problem, you can safely delete the ``_build`` and then use ``make html``` to generate a fresh copy. .. code-block:: bash :caption: From the host rm -r sphinx/_build/html docker-compose exec sphinx bash -c "cd /opt/sphinx && make html" .. Image placeholders .. |default-sphinx| image:: images/default-sphinx-page.png .. |rtd-theme| image:: images/rtd-sphinx-page.png