SphinxTutorial Documentation

Transcription

1 SphinxTutorial Documentation Release 1.0 Anthony Scemama April 12, 2013

2

3 CONTENTS 1 Introduction 3 2 Creating a new Sphinx project 5 3 restructuredtext Sections Paragraphs Lists Inline markup Images Tables Footnotes Citations Hyperlinks Comments Substitutions Documenting your code Autodoc Displaying some code Cross-referencing Python domain Standard domain Arbitrary locations Examples 25 7 Indices and tables 27 Bibliography 29 Python Module Index 31 Index 33 i

4 ii

5 Contents: CONTENTS 1

6 2 CONTENTS

7 CHAPTER ONE INTRODUCTION Sphinx is a tool to create documentation It was created for the new Python documentation It uses restructuredtext (rst) as its markup language 3

8 4 Chapter 1. Introduction

9 CHAPTER TWO CREATING A NEW SPHINX PROJECT Run the configuration script: $ sphinx-quickstart Welcome to the Sphinx quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: 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. > Separate source and build directories (y/n) [n]: y 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: SphinxTutorial > Author name(s): Anthony Scemama 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 or 3.0a1. If you don t need this dual structure, just set both to the same value. > Project version: 1.0 > Project release [1.0]: 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]: Sphinx can also add configuration for epub output: 5

10 > Do you want to use the epub builder (y/n) [n]: Please indicate if you want to use one of the following Sphinx extensions: > 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]: > pngmath: include math, rendered as PNG images (y/n) [n]: y > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y Note: pngmath and mathjax cannot be enabled at the same time. pngmath has been deselected. > 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 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 Creating file./source/conf.py. Creating file./source/index.rst. Creating file./makefile. Finished: An initial directory structure has been created. You should now populate your master file./source/index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck. The source directory contains a conf.py configuration file, and the index.rst file which is the main page of your documentation:.. SphinxTutorial documentation master file, created by sphinx-quickstart on Tue Apr 9 17:58: You can adapt this file completely to your liking, but it should at least contain the root toctree directive. Sphinx Tutorial ========================================== Contents:.. toctree:: :maxdepth: 1 intro install rst documenting cross examples Indices and tables ================== 6 Chapter 2. Creating a new Sphinx project

11 * :ref: genindex * :ref: modindex * :ref: search toctree is the table of contents of your document. Below, you can insert the file names (without the.rst extension) which correspond to each section. toctree is a rst directive, so: Arguments are given after the double colon (:) Options are given after the arguments (maxdepth) The first line of the content must be indented to the same level as the options are. A Makefile has been created to let you build the documentation in many different formats (HTML, pdf, test, man, etc...) 7

12 8 Chapter 2. Creating a new Sphinx project

13 CHAPTER THREE RESTRUCTUREDTEXT A rst file looks like this: 1 ================= 2 Cross-referencing 3 ================= 4 5 Python domain :py:mod: 9 Module :py:func: 12 Function :py:data: 15 Module-level variable :py:const: 18 A defined constant :py:class: 21 Class :py:meth: 24 Method of an object :py:attr: 27 Data attribute of an object :py:exc: 30 Exception :py:obj: 33 Object of unspecified type Example: code-block:: rst function:: pyfunc() Describes a Python function. 9

14 43 44 Reference to :func: pyfunc function:: pyfunc() Describes a Python function Reference to :func: pyfunc Standard domain This domain is used to document command-line programs option:: name args, name args, Command-line option envvar:: name 62 Environment variable program:: name 65 Produces no output, but tells sphinx that all the following options 66 refer to this program Example: code-block:: rst program:: qmcchem envvar:: QMCCHEM_NET_INTERFACE Network interface to use for communications option:: -t <property>, --table <property> Print a table for the convergence of <property> The option -t refers to :option: qmcchem -t program:: qmcchem envvar:: QMCCHEM_NET_INTERFACE Network interface to use for communications option:: -t <property>, --table <property> Print a table for the convergence of <property> The option -t refers to :option: qmcchem -t _arbitrary-location: Chapter 3. restructuredtext

15 101 Arbitrary locations Sections 105 ^^^^^^^^ In rst, labels can be put anywhere in the text. If a label is placed before a section title, 108 it will refer to the section. For example: code-block:: rst _arbitrary-location: Arbitrary locations This refers to the section :ref: arbitrary-location This refers to the section :ref: arbitrary-location Such labels work across different files Downloadable documents 125 ^^^^^^^^^^^^^^^^^^^^^^^ Documcents that are intended to be downloaded can be referenced like this: code-block:: rst The :download: Verlet file <verlet.pdf> contains the exercises The :download: Verlet file <verlet.pdf> contains the exercises. It is also very easy to read in a terminal. 3.1 Sections ================= This is a heading ================= This is a section ================= This is a subsection This is a subsubsection ^^^^^^^^^^^^^^^^^^^^^^^ Paragraphs ========== 3.1. Sections 11

16 3.2 Paragraphs Paragraphs are separated by blank lines. All the text in a paragraph should have the save level of indentation Line blocks Line breaks are preserved: These lines are broken exactly like in the source file. These lines are broken exactly like in the source file Definitions A definition is represented as one line of tex containing the term to define, and its definition as an indented paragraph. sphinx A winged monster of Thebes, having a woman s head and a lion s body. It asked a riddle, killing those who failed to solve it, until... sphinx A winged monster of Thebes, having a woman s head and a lion s body. It asked a riddle, killing those who failed to solve it, until Literal blocks A paragraph containing only two colons indicates that the following indented or quoted text is a literal block :: A paragraph containing only two colons indicates that the following indented or quoted text is a literal block :: A paragraph containing only two colons indicates that the following indented or quoted text is a literal block Code blocks Code blocks are similar to Literal blocks, but with syntax highlighting:.. code-block:: python :emphasize-lines: 3,5 def some_function(): interesting = False print This line is highlighted. print This one is not... print...but this one is. 12 Chapter 3. restructuredtext

17 def some_function(): interesting = False print This line is highlighted. print This one is not... print...but this one is. 3.3 Lists Bulleted lists start with a *, + or - Numbered lists start with a #, a number or a letter a. followed by a period. They can be nested, but the nested list must start with a blank line. * First item * Second item * First nested item * Second nested item * Third nested item * Third item #. First item #. Second item #. Third item i. First item ii. Second item iii. Third item 1) This also works 2) Fantastic! First item Second item First nested item Second nested item Third nested item Third item 1. First item 2. Second item 3. Third item 1. First item 2. Second item 3. Third item 1. This also works 2. Amazing! 3.3. Lists 13

18 3.3.1 Options lists For listing command line options: -b, --bytes=list select only these bytes -c, --characters=list select only these characters -d, --delimiter=delim use DELIM instead of TAB for field delimiter -f, --fields=list select only these fields; also print any line that contains no delimiter character, unless the -s option is specified 3.4 Inline markup text in italics : text in *italics* text in italics : text in **italics** this is a code sample : this is a code sample Abbreviations are defined like this: The full explanation of :abbr: SCF (Self-Consistent Field) is displayed in a tool-tip The full explanation of SCF (Self-Consistent Field) is displayed in a tool-tip, or output only once when using the latex output. OS commands use :command: ls, for ls File names are displayed using :file:/bin/ls for /bin/ls Keystrokes are written as :kbd: Control-c Control-v for Control-c Control-v Similarly, :manpage: ls refers to the man page of ls Menu selections are described as: :menuselection: File --> Open for File Open Literal text with a variable part can be displayed as followed: Decompress the :samp: EZFIO.{version}.tar.gz file. Decompress the EZFIO.version.tar.gz file. 3.5 Images.. image:: sphinx.* 14 Chapter 3. restructuredtext

19 If the image exists in different format, the most suitable format will be chosen. For example, when building the pdf documentation, the pdf image will be chosen. For HTML documentation, png or jpeg will be prefered. 3.6 Tables Simple tables are easy to write. They must contain more than one row, and the first column can t contain multiple lines. ===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== ======= A B A and B False False False True False False False True False True True True Grid tables are more elaborate: Header row, column 1 Header 2 Header 3 Header 4 (header rows optional) +========================+==========+==========+==========+ body row 1, column 1 column 2 column 3 column Tables 15

20 body row Header row, column 1 (header rows optional) Header 2 Header 3 Header 4 body row 1, column 1 column 2 column 3 column 4 body row Footnotes For footnotes, use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the document after a Footnotes rubric heading, like so: A good rst tutorial [#f1]_ is located at the bottom[#f2]_ of the page... rubric:: Footnotes.. [#f1] Here: [#f2] Text of the second footnote. A good rst tutorial 1 is located at the bottom 2 of the page. 3.8 Citations All citations can be referenced from all files. Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #. The rst specification [RefMarkup]_ is available on the web... [RefMarkup] The rst specification [RefMarkup] is available on the web. 3.9 Hyperlinks rst understands URLs and addresses, and make them as links automatically. If the text should not be the address, the syntax is Link text < _ The link and the target definition can also be saparated. This is a paragraph that contains a link _. The link points to a web site < _. This web site is Send me an scemama@irsamc.ups-tlse.fr.. _a link: This is a paragraph that contains a link. The link points to a web site. This web site is Send me an scemama@irsamc.ups-tlse.fr 1 Here: 2 Text of the second footnote. 16 Chapter 3. restructuredtext

21 3.10 Comments Comments paragraphs starting with.., and where the indentation is below the 1st word of the paragraph... This is a multi-line comment paragraph Substitutions Some macros can be defined using.. name replace:: replacement *text* For example:.. lcpq replace:: Laboratoire de Chimie et Physique Quantiques < sphinx image:: sphinx.jpg :width: 50 I work at the lcpq, and I like sphinx! I work at the Laboratoire de Chimie et Physique Quantiques < and I like! Comments 17

22 18 Chapter 3. restructuredtext

23 CHAPTER FOUR DOCUMENTING YOUR CODE Documenting a function is done like this:.. function:: create_useful_function(number) Returns a new function built upon execution, that depends on the parameter number. create_useful_function(number) Returns a new function built upon execution, that depends on the parameter number. This function can be linked in your documentations as follows: The function :func: create_useful_function is referenced in this example. The function create_useful_function() is referenced in this example. 4.1 Autodoc In Python coding, it is common to put the documentation inside the code as docstrings: 1 #!/usr/bin/python 2 """This is the decorator example of the Metaprogramming 3 section.""" 4 5 class MyClass(object): 6 """Dummy class with three functions, appearing 7 as the decorator example of Metaprogramming.""" 8 9 def init (self): 10 """Initialization function.""" 11 self.one = def test1(self): 14 """Returns self.one""" 15 return self.one def test2(self): 18 """Calls the :func: test1 function""" 19 tmp = self.test1() 20 return tmp 21 19

24 22 23 functions = [ f for f in MyClass. dict.items() \ 24 if str(f[1]).startswith( <function ) ] text = """ 27 MyClass.%(name)s_original = MyClass.%(name)s 28 def %(name)s(self, *args, **kw): 29 \"\"\"Decorated version of %(name)s_original.\"\"\" 30 print "Enter %(name)s" 31 result = self.%(name)s_original(*args,**kw) 32 print "Leave %(name)s" 33 return result 34 MyClass.%(name)s = %(name)s 35 """ for name, f in functions: 38 exec text%locals() def testing(): 42 """Function to test the decoration.""" 43 A = MyClass() 44 print A.test2() if name == " main ": 47 testing() Such strings are interpreted by the pydoc tool, which is part of the Python distribution. Sphinx is also able to read your code and use the docstrings to add them to your Sphinx documentation automatically. You can auto-document a single function or a whole module... autofunction:: decorator.testing decorator.testing() Function to test the decoration... automodule:: decorator :members: This is the decorator example of the Metaprogramming section. class decorator.myclass(*args, **kw) Dummy class with three functions, appearing as the decorator example of Metaprogramming. test1(*args, **kw) Decorated version of test1_original. test1_original() Returns self.one test2(*args, **kw) Decorated version of test2_original. test2_original() Calls the test1() function decorator.f(self ) Initialization function. 20 Chapter 4. Documenting your code

25 decorator.test1(self, *args, **kw) Decorated version of test1_original. decorator.test2(self, *args, **kw) Decorated version of test2_original. decorator.testing() Function to test the decoration. 4.2 Displaying some code A whole file can be included using:.. literalinclude:: deocrator.py (see example above). Using directives, only part of the file can be shown, line numbers can be dispayed, etc:.. literalinclude:: decorator.py :language: python :pyobject: testing :linenos: 1 def testing(): 2 """Function to test the decoration.""" 3 A = MyClass() 4 print A.test2() 4.2. Displaying some code 21

26 22 Chapter 4. Documenting your code

27 CHAPTER FIVE CROSS-REFERENCING 5.1 Python domain :py:mod: Module :py:func: Function :py:data: Module-level variable :py:const: A defined constant :py:class: Class :py:meth: Method of an object :py:attr: Data attribute of an object :py:exc: Exception :py:obj: Object of unspecified type Example:.. function:: pyfunc() Describes a Python function. Reference to :func: pyfunc. pyfunc() Describes a Python function. Reference to pyfunc(). 5.2 Standard domain This domain is used to document command-line programs... option:: name args, name args,... Command-line option.. envvar:: name Environment variable.. program:: name Produces no output, but tells sphinx that all the following options refer to this program Example: 23

28 .. program:: qmcchem.. envvar:: QMCCHEM_NET_INTERFACE Network interface to use for communications.. option:: -t <property>, --table <property> Print a table for the convergence of <property> The option -t refers to :option: qmcchem -t QMCCHEM_NET_INTERFACE Network interface to use for communications -t <property>, -table <property> Print a table for the convergence of <property> The option -t refers to qmcchem -t 5.3 Arbitrary locations Sections In rst, labels can be put anywhere in the text. If a label is placed before a section title, it will refer to the section. For example:.. _arbitrary-location: Arbitrary locations This refers to the section :ref: arbitrary-location This refers to the section Arbitrary locations Such labels work across different files Downloadable documents Documcents that are intended to be downloaded can be referenced like this: The :download: Verlet file <verlet.pdf> contains the exercises. The Verlet file contains the exercises. 24 Chapter 5. Cross-referencing

29 CHAPTER SIX EXAMPLES You have seen the HTML output,now look at the following outputs: Single HTML file Latex Text Man pages Info 25

30 26 Chapter 6. Examples

31 CHAPTER SEVEN INDICES AND TABLES genindex modindex search 27

32 28 Chapter 7. Indices and tables

33 BIBLIOGRAPHY [RefMarkup] 29

34 30 Bibliography

35 PYTHON MODULE INDEX d decorator, 20 31

36 32 Python Module Index

37 INDEX Symbols -t <property>, table <property> qmcchem command line option, 24 C create_useful_function() (built-in function), 19 D decorator (module), 20 E environment variable QMCCHEM_NET_INTERFACE, 24 F f() (in module decorator), 20 M MyClass (class in decorator), 20 P pyfunc() (built-in function), 23 Q qmcchem command line option -t <property>, table <property>, 24 T test1() (decorator.myclass method), 20 test1() (in module decorator), 20 test1_original() (decorator.myclass method), 20 test2() (decorator.myclass method), 20 test2() (in module decorator), 21 test2_original() (decorator.myclass method), 20 testing() (in module decorator), 20, 21 33