Sphinx Cookbook ############### Sphinx is the name of the software application used to build documentation from reStructured text files. reStructured text is a type of markdown, and reStructured text files have an *rst* extension. E.g., *phoneid.rst*. Sphinx Documentation ******************** For information about how to use Sphinx, see `Sphinx Documentation Generator - Documentation Contents `_ Sphinx Terminology ****************** Before you can become proficient at using Sphinx, you must understand Sphinx-specific terminology. Source Directory ================ The **Source Directory** is the *Root Directory* of a docset. E.g., `C:\\Users\\Chris\\src\\python_rest_api\\doc\\user\\v1\\source\\` The **Source Directory** always contains the Sphinx build **Sphinx Configuration File** - *conf.py*. The Configuration File is a data store that contains the set of Sphynx options and customization details for the doc set (for example, the Project Name, and the name and location of the Template you want to use). The **Source Directory** also contains the **Master File** - *index.rst*. The **Master File** is the *root* topic for your collection. It contains the [**/./. toctree::**] *directive*. You list the names of the second-level topics beneath this directive, and it automatically links them into the doc set (and into the table of contents). For example, the Source Directory for the TeleSign Python SDK project is .. code-block:: shell-session %USERPROFILE%\\python_telesign_sdk\\doc\\ Working Directory ================= The Working directory is one level up from the Source directory. E.g., C:\\Users\\Chris\\src\\python_rest_api\\doc\\user\\v1\\ When you use a *Make file* to run Sphinx, the file **make.bat** must reside in the **Working Directory**. This directory contains a folder called **source**, and another folder called **build)**. Installing Sphinx ***************** 1. Open an Administrative command prompt (not the Python shell) and enter the command: *easy_install -U sphinx*. The install process takes about a minute to complete. .. Note:: This procedure assumes you have already installed Python, Minw32, and Easy Install. Updating your Sphinx Installation ********************************* I discovered that if you have already installed Sphinx once and you want to update it, you must update each of Sphinx's dependencies yourself! .. code-block:: bro %USERPROFILE%>easy_install -U sphinx %USERPROFILE%>easy_install -U docutils %USERPROFILE%>easy_install -U Jinja2 %USERPROFILE%>easy_install -U Pygments %USERPROFILE%>easy_install -U PIL Make **** **GNU Make** is a program that simplifies the building process. Install Make ============ 1. Download the make installer from `Make forf Windows _`. On the landing page, under the heading titled **Download**, right-click *Setup program*, and then save the file to your **Downloads** folder. #. Run the Installer as Administrator. #. Create a new environment variable MAKE_HOME = C:\Program Files (x86)\GnuWin32\ #. Add it to the Path ;%MAKE_HOME%;%MAKE_HOME%\\bin Reboot your computer to make the environment variables take affect. sphinx-build ************ This is the executable that actually builds the docs. There are two files with this name: an executable, and a Python script -- and you can use either one! .. _xref-sphinx-build-options: sphinx-build Options ==================== ====== =============== =========== Option Value Description ====== =============== =========== -b The builder to use (the default is html). -a Write all files. The default is to write only new and changed files. -E Don't use the cached version of the source files. Read all of the original files again. -t Include just the blocks with . This is for conditionally building. -d Path for the cached environment and the doctree files (default: outdir/.doctrees). -c Path where configuration file (conf.py) is located. (default: same as sourcedir). -C Use no config file at all. Use the -D options only. -D Override a particular setting in configuration file. -A Pass a value into the templates. For HTML builder only. -n Enable Nit-picky mode - and warn about all missing references. -N Do not output in color. -q No output on stdout, just warnings on stderr. -Q No output at all, not even warnings. -w Write warnings (and errors) to the specified file. -W Turn warnings into errors. -P Run Pdb on exception. ====== =============== =========== Modes ----- To write new and changed files Omit the -a switch, and omit the filenames. To write all files inclde the -a switch. To write particular files Include those filenames. The sphinx-build Executible =========================== The *sphinx-build* executible calls the Python script to build the python documentation. .. code-block:: bro C:\\Python27\\Scripts\\sphinx-build.exe sphinx-build Usage ------------------ .. code-block:: bro $ sphinx-build [options] sourcedir builddir [filenames] sphinx-build Example -------------------- .. code-block:: bro %USERPROFILE%>sphinx-build [options] sourcedir outdir [filenames...] The sphinx-build-script Python Script ===================================== Usage .. code-block:: bro C:\\Python27\\Scripts\\sphinx-build-script.py [options] sourcedir outdir [filenames...] **Make** File Defaults ======================= These are the :ref:`Sphinx Build Options ` that **Make** uses. E (Environment) - rebuild all files, not just changed files. D (override value in conf.py with this one) = "version=1.0.4". b (builder name) = "html" Examples ======== sourcedir = C:\\Users\\Chris\\python_telesign_sdk\\doc\\. builddir = C:\\Users\\Chris\\python_telesign_sdk\\doc\\_build\\1.0.4\\. filenames = not used. How To ****** How to Install the TeleSign Python SDK ====================================== python setup.py doc: When you install the TeleSign Python SDK, as part of its install procedure, it calls sphinx-build and it builds the docs. status = subprocess.call(["sphinx-build", "-E", "-D", "version=%s" % version, "-b", mode, "doc", path]) version = "1.0.4" path = "doc/_build/%s" % version mode = "html" Expanded -------- status = subprocess.call(["sphinx-build", "-E", "-D", "version=1.0.4", "-b", "html", "doc", "doc/_build/1.0.4"]) Build the Docs ============== You must run make from the directory that contains make.bat E.g., C:\\Users\\Chris\\src\\python_rest_api\\doc\\user\\v1\\ This directory is one level *above* the directory you use for sphinx_build. **This is what is inside make.bat** .. code-block:: bro if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end ) Running make html ----------------- **This is what the command output looks like** .. code-block:: bro C:\\Users\\Chris\\src\\python_rest_api\\doc\\user\\v1>make html Running Sphinx v1.1.3 building [html]: all source files updating environment: 33 added, 0 changed, 0 removed reading sources... [ 3%] content/about-rest-api reading sources... [ 6%] content/auth-examples reading sources... [ 9%] content/auth-headers reading sources... [ 12%] content/canonicalization reading sources... [ 15%] content/phoneid reading sources... [ 18%] content/phoneid-contact reading sources... [ 21%] content/phoneid-live reading sources... [ 24%] content/phoneid-score reading sources... [ 27%] content/phoneid-standard reading sources... [ 30%] content/positional reading sources... [ 33%] content/reference reading sources... [ 36%] content/requests reading sources... [ 39%] content/responses reading sources... [ 42%] content/rest-auth reading sources... [ 45%] content/telesign-resources reading sources... [ 48%] content/time-stamp reading sources... [ 51%] content/using-the-api reading sources... [ 54%] content/verify reading sources... [ 57%] content/verify-call reading sources... [ 60%] content/verify-sms reading sources... [ 63%] content/xt/xt-cleansing-codes reading sources... [ 66%] content/xt/xt-country-codes reading sources... [ 69%] content/xt/xt-error-codes reading sources... [ 72%] content/xt/xt-http-response-status-codes reading sources... [ 75%] content/xt/xt-language-tags reading sources... [ 78%] content/xt/xt-phone-type-codes reading sources... [ 81%] content/xt/xt-score reading sources... [ 84%] content/xt/xt-time-zones reading sources... [ 87%] content/xt/xt-transaction-codes reading sources... [ 90%] content/xt/xt-use-case-codes reading sources... [ 93%] content/xt/xt-verify-status-call reading sources... [ 96%] content/xt/xt-verify-status-sms reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [ 3%] content/about-rest-api writing output... [ 6%] content/auth-examples writing output... [ 9%] content/auth-headers writing output... [ 12%] content/canonicalization writing output... [ 15%] content/phoneid writing output... [ 18%] content/phoneid-contact writing output... [ 21%] content/phoneid-live writing output... [ 24%] content/phoneid-score writing output... [ 27%] content/phoneid-standard writing output... [ 30%] content/positional writing output... [ 33%] content/reference writing output... [ 36%] content/requests writing output... [ 39%] content/responses writing output... [ 42%] content/rest-auth writing output... [ 45%] content/telesign-resources writing output... [ 48%] content/time-stamp writing output... [ 51%] content/using-the-api writing output... [ 54%] content/verify writing output... [ 57%] content/verify-call writing output... [ 60%] content/verify-sms writing output... [ 63%] content/xt/xt-cleansing-codes writing output... [ 66%] content/xt/xt-country-codes writing output... [ 69%] content/xt/xt-error-codes writing output... [ 72%] content/xt/xt-http-response-status-codes writing output... [ 75%] content/xt/xt-language-tags writing output... [ 78%] content/xt/xt-phone-type-codes writing output... [ 81%] content/xt/xt-score writing output... [ 84%] content/xt/xt-time-zones writing output... [ 87%] content/xt/xt-transaction-codes writing output... [ 90%] content/xt/xt-use-case-codes writing output... [ 93%] content/xt/xt-verify-status-call writing output... [ 96%] content/xt/xt-verify-status-sms writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded. Build finished. The HTML pages are in build/html. **Building Sphinx docs using Sphinxbuild** Syntax .. code-block:: bro %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html **Legend** .. code-block:: bro SPHINXBUILD = sphinx-build builder (-b) = html BUILDDIR = _build SPHINXOPTS = ""- to match python setup.py doc, this needs -E (rebuild all docs). cache path (-d) = _build/doctrees - Pickled version of the parsed source files (make.bat does add this option). ALLSPHINXOPTS = -d %BUILDDIR%/doctrees %SPHINXOPTS% = -d _build/doctrees %SPHINXOPTS% **Example** You run sphinx-build from the directory that contains index.rst and conf.py (for example, C:\\Users\\Chris\\src\\python_rest_api\\doc\\user\\v1\\source). .. code-block:: bro sphinx-build -b html -E . _build/html With Tags .. code-block:: bro sphinx-build -b html -E -t html . _build/ To build a PDF using LaTeX .. code-block:: bro sphinx-build -b latexpdf -E . _build/pdf To build a PDF .. Note:: Don't try to build the PDF version of the docs because you don't get good results due to a bug somewhere in Sphinx. .. code-block:: bro sphinx-build -b pdf -E . _build/pdf With Tags .. code-block:: bro sphinx-build -b pdf -E -t pdf . _build/pdf To get **Make** to work, yhou have to set a value for *SPHINXOPTS* (it actaully has no value in make.bat!). To rebuild all files (not just changed files) .. code-block:: bro set SPHINXOPTS=-E For the Python SDK Docs, to see the revisions that you made in api.py, you have to re-install the SDK, and then build the docs. 1. Open a command prompt. You can use the *Git BASH*. 2. Change to the SDK directory (\\python_telesign_sdk\\). 3. Reinstall the SDK .. code-block:: bro python setup.py install 4. Rebuild the docs .. code-block:: bro python setup.py doc reST Reference ************** Directives ========== .. code-block:: bro .. rubric:: In this Section toctree ======= .. code-block:: bro .. toctree:: :maxdepth: 2 :numbered: :titlesonly: :glob: :hidden: Hyperlinking ============ http://sphinx-doc.org/markup/inline.html?highlight=hyperlink To another topic in the same doc set ------------------------------------ .. code-block:: bro :ref:`xref-topic-file` Example ^^^^^^^ .. code-block:: bro You can get the results automatically by subscribing for a :ref:`xref-transaction-callback`. To a position in the same topic ------------------------------- To a Section Title ^^^^^^^^^^^^^^^^^^ .. code-block:: bro `section title`_ To Any Point in the Same Topic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You must first create and place a reference directive immediately before the target content. Example of Target Reference Directive .. code-block:: bro .. _xref-verify-2way-sms-resource_uri-object: Example Usage .. code-block:: bro After you've made your verification request, you can retrieve the verification results by sending a **GET** request to the ``verify`` resource, with a :ref:`reference ` to your original service request for the :ref:`Subresource Identifier `. An Example of the Resulting HTML URL .. code-block:: http file:///%USERPROFILE%/src/python_rest_api/doc/user/v1/build/html/content/verify-2way-sms.html#xref-verify-2way-sms-resource-uri-object You Provide Your Own Link Text ------------------------------ .. code-block:: bro :ref:`Link title ` :ref:`reference ` Example ^^^^^^^ .. code-block:: bro The phone number must include its associated :ref:`country code ` (1 for North America). To a Web URL ------------ .. code-block:: bro `Link text `_ Admonitions =========== .. code-block:: http ".. attention::", ".. caution::", ".. danger::", ".. error::", ".. hint::", ".. important::", ".. note::", ".. tip::", ".. warning::". Note: only "note" renders with nice formatting. E.g., .. Note:: You must base64 decode it to use in generating the signature. .. tip:: You can get the results automatically by subscribing for a transaction callback. Pigment Syntax Coloring ======================= E.g., .. code-block:: http .. highlight:: javascript Tags ==== .. code-block:: http .. tag:: The 'tags' that are used as switches in the "only::" directive are accessible in the conf.py file with the 'tags' object, so you might want to investigate using build command line tags in conjunction with "only::" in your sources, plus a conf.py construction that looks something like this: .. code-block:: http if tags.has('modeA'): # exclude patterns should throw out any modeB-only files exclude_patterns = exclude_patterns + ['modeB_toc.rst'] master_doc = 'modeA_toc.rst' else if tags.has('modeB'): # exclude patterns should throw out any modeA-only files exclude_patterns = exclude_patterns + ['modeA_toc.rst'] master_doc = 'modeB_toc.rst' else: # some Building an HTML File From an rst File ====================================== Run the *rst2html* Python script on the rst file. 1. Open a DOS Command Prompt Window. 2. Navigate to the directory that contains the REst file you want to convert. 3. Type *rst2html.py \\*.rst \\*.html*. Example ------- .. code-block:: http rst2html.py Readme.rst Readme.html Switches -------- To get a footer with a link to the source file, date & time of processing, and links to the Docutils project .. code-block:: http rst2html.py -stg Readme.rst Readme.html Donn Trenton's Original Notes ***************************** I Installed Python & the `Sphinx Python Documentation Generator `_. To build docs ============= Run the command 'make html' from the \\doc directory. The resulting html files are written to this directory .. code-block:: bro C:\\Users\\Chris\\python_telesign_sdk\\doc\\_build\\html\\ The main web page is the file .. code-block:: bro %USERPROFILE%\\python_telesign_sdk\\doc\\_build\\html\\index.html Alternatively, you can run this command from the root directory of the telesign source (one up from \\doc): .. code-block:: bro python setup.py doc The resulting html files are written to this directory: .. code-block:: bro C:\\Users\\Chris\\python_telesign_sdk\\doc\\_build\\1.0.4\\ Doc build directories --------------------- For Testing .. code-block:: http /src/ts/python_rest_api/doc/test/ For Public User Docs .. code-block:: http /src/ts/python_rest_api/doc/user/ Sphinx build commands --------------------- Set up a new build directory To set up a build for a new documentation set, create a directory to for the doc set. This should be a subdirectory under /draft (for doc development and testing) or /user (for published docs). Invoke the following command to set up the source directory, the makefile, and the configuration file: .. code-block:: http $ sphinx-quickstart When you run this command, it asks you a series of questions. Typically you can accept the defaults, with the following exceptions: .. code-block:: http - Autodoc extensions: Y - Generate makefile: Y (so that you only have to run 'make html' to build) > Separate source and build directories (y/N): Y (this structure is easier to maintain) > Source file suffix [.rst or .txt]: .rst (we should decide on a standard) Build HTML from the current makefile ------------------------------------ After you run quickstart, the build is set up, and you can then run the following command to rebuild the docs: .. code-block:: http $ make html The top node contents doc is "index.rst." If you add new source files to the build, you have to update index.rst. Rebuild the makefile -------------------- If you change the files in your build, you might have to rebuild the makefile. If you're just adding files you can just add them to index.rst and make build will figure it out. But if you rename files, move, or and remove files it can get confused. To rebuild the makefile, use sphinx-build. .. code-block:: http $ sphinx-build -b html source build List of key quickstart answers ------------------------------ .. Note:: Accept the default value unless otherwise indicated below. You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. .. code-block:: http Separate source and build directories (y/N) [n]: y The project name will occur in several places in the built documentation. .. code-block:: http Project name: TeleSign REST API Author name(s): TeleSign Corporation In conf.py, this sets the following: .. code-block:: http project = u'TeleSign REST API' copyright = u'2012, TeleSign Corporation' Note that "author name" is what appears in the copyright notice. Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. .. code-block:: http Project version: Project release: Accept the default, which is no version or release number. In conf.py, this sets version = '' and release = ''. The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. .. code-block:: http Source file suffix [.rst]: .rst In conf.py, source_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. .. code-block:: http Name of your master document (without suffix) [index]: index Please indicate if you want to use one of the following Sphinx extensions: .. code-block:: http epub: Do you want to use the epub builder (y/N) [n]: n autodoc: automatically insert docstrings from modules (y/N) [n]: y doctest: automatically test code snippets in doctest blocks (y/N) [n]: n intersphinx: link between Sphinx documentation of different projects (y/N) [n]: n todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: n coverage: checks for documentation coverage (y/N) [n]: n pngmath: include math, rendered as PNG images (y/N) [n]: n mathjax: include math, rendered in the browser by MathJax (y/N) [n]: n ifconfig: conditional inclusion of content based on config values (y/N) [n]: n viewcode: include links to the source code of documented Python objects (y/N) [n]: n A Makefile and a Windows command file can be generated for you so that you only have to run make html instead of invoking *sphinx-build* directly. .. code-block:: http Create Makefile? (Y/n) [y]: y Create Windows command file? (Y/n) [y]: y After setup creates the config file (conf.py), open the file and change the HTML theme; TeleSign uses the *sphinxdoc* theme: Options for HTML output ----------------------- The theme to use for HTML and HTML Help pages. See the documentation for a list of builtin themes. .. code-block:: http html_theme = 'sphinxdoc' Resources ========= RST – reStructuredText ---------------------- .. code-block:: http http://people.ee.ethz.ch/~creller/web/tricks/reST.html How do I convert a word document to reStructured text? ------------------------------------------------------ .. code-block:: http http://groups.google.com/group/sphinx-dev/browse_thread/thread/77b0db51eb994775?pli=1 Docutils Link List ------------------ .. code-block:: http http://docutils.sourceforge.net/docs/user/links.html#import An Introduction to reStructuredText ----------------------------------- .. code-block:: http http://docutils.sourceforge.net/docs/ref/rst/introduction.html Pandoc ====== You use Pandoc to convert HTML to RST. .. code-block:: http http://johnmacfarlane.net/pandoc/ This is especially useful for tables. Create a table in Microsoft Expression Web, switch to code view, copy and paste into an .htm file, then run Pandoc on it to convert it to an .rst file. E.g., ----- .. code-block:: shell-session pandoc -f html -t rst -o table1.txt table1.htm To install Pandoc ----------------- .. code-block:: http http://johnmacfarlane.net/pandoc/installing.html Pandoc User’s Guide ------------------- .. code-block:: http http://johnmacfarlane.net/pandoc/README.html Pandoc Commands --------------- .. code-block:: shell-session pandoc -f [from_format] -t [to_format] -o [output_file] [input_file] .. code-block:: shell-session pandoc -f docx -t rst -o PVSOAPRST.txt PVSOAPTEST.docx (this doesn't work; pandoc doesn't support conversion from .docx) .. code-block:: shell-session pandoc -f html -t rst -o PVSOAPRST1.txt PVSOAPTEST-HTML.htm (have to save the .docx file as .htm (web page) first) .. code-block:: shell-session pandoc -f html -t rst -o PVSOAPRST2.txt PVSOAPTEST-HTML.htm (have to save the .docx file as .htm (filtered web page) first) Pandoc Results -------------- .. code-block:: shell-session C:\\Users\\Donn\\My Documents\\!telesign\\Phone Verification>pandoc -f docx -t rst -o PVSOAPRST.txt PVSOAPTEST.docx .. code-block:: shell-session pandoc: Unknown reader: docx .. code-block:: shell-session C:\\Users\\Donn\\My Documents\\!telesign\\Phone Verification>pandoc -f html -t rst -o PVSOAPRST1.txt PVSOAPTEST-HTML.htm .. code-block:: shell-session pandoc: PVSOAPTEST-HTML.htm: hGetContents: invalid argument (invalid UTF-8 byte sequence) .. code-block:: shell-session C:\\Users\\Donn\\My Documents\\!telesign\\Phone Verification>pandoc -f html -t rst -o PVSOAPRST2.txt PVSOAPTEST-HTMF.htm .. code-block:: shell-session pandoc: PVSOAPTEST-HTMF.htm: hGetContents: invalid argument (invalid UTF-8 byte sequence) Advice & Caveats ================ Line breaks ----------- You can create the source docs in notepad on a Windows computer, but the line breaks are different in Windows vs Linux. I think Windows is CR+LF and Linus is only one of those. Anyway, if you go from Windows -> Linux, the text will look okay, but will contain invisible hard line breaks. You might have to run a test build to find all of them. Workaround ^^^^^^^^^^ Switch Notepad to *no text wrapping*, and then copy text. Code blocks ----------- Mark code blocks for syntax highlighting (using the Pygments add-in). .. code-block:: bro .. code-block:: xxx Where xxx is the name of the Pygments lexor for that kind of code. Each line of the code block must be indented with three spaces For example, this is how you indicate a code block for HTML .. code-block:: bro { // indent at least two spaces code block; } I use the "bro" lexor for REST code. "bro" is actually designed for some other kind of code, but I use it since there isn't one that gives me pretty looking REST code. For HTML ^^^^^^^^ .. code-block:: bro .. code-block:: http For JSON ^^^^^^^^ .. code-block:: bro .. code-block:: json The 'include' Directive ----------------------- To include a block of text from an external file, use the 'include' directive: .. code-block:: bro .. include:: inclusion.txt I think the inclusion file has to be .txt; .rst did not work Hypertext Links --------------- For inline web links (links to external files or websites): .. code-block:: bro `Link text `_ Section structure ----------------- lines can be made with the following characters: .. code-block:: bro = - ` : ' " ~ ^ _ * + # < > I like to use ^^^^^^^^^^^^^ Topic Title (only one per source content file): # Heading 1: * Heading 2: = Heading 3: - Heading 4: ^ Heading 5: " Sphinx Project Config Files =========================== Sphinx Roles .. code-block:: shell-session C:\\Python27\\Lib\\site-packages\\Sphinx-1.1.3-py2.7.egg\\sphinx\\roles.py The Sphinx templates .. code-block:: shell-session C:\\Python27\\Lib\\site-packages\\Sphinx-1.1.3-py2.7.egg\\sphinx\\themes\\ MiKTex ====== This software is required to create the PDF version of doc from LaTeX files in Sphinx. Home Page --------- .. code-block:: http http://miktex.org Download Page ------------- .. code-block:: http http://miktex.org/download Click the drop-down arrow to show the "Other" downloads.