1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
[[sphinx]]
== Sphinx documentation
Erlang.mk includes targets for running
http://www.sphinx-doc.org/[Sphinx documentation generator], which can produce
documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and
others.
=== Writing Sphinx documentation
Sphinx generates documentation form a set of
http://www.sphinx-doc.org/en/stable/rest.html[reST] documents. There is
a http://www.sphinx-doc.org/en/stable/tutorial.html[quick start guide] on
Sphinx' website. For Erlang.mk, we'll set up a minimal environment instead.
=== Basic setup
By default, Erlang.mk expects Sphinx documentation to be placed in 'doc'
directory, with 'doc/conf.py' config file in particular. The file contains
information about the project, among the other things.
A minimal 'doc/conf.py' will look similar to this:
[source,python]
----
project = 'My Project'
version = '0.0'
release = '0.0.1'
master_doc = 'index'
source_suffix = '.rst'
----
It points to a 'doc/index.rst' document. A simple skeleton includes a table of
contents for all documentation, and links to generated index of terms and
a search page:
[literal]
----
My Project
==========
Contents:
.. toctree::
:maxdepth: 2
other_page
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
----
The skeleton above has a link to one other page, 'doc/other_page.rst'. Simple
header with some text will do for now:
[literal]
----
Other Page
==========
Lorem ipsum dolor sit amet...
----
The files above are enough to build HTML documentation to 'html' directory.
[source,bash]
$ make docs # all the docs, including EDoc and AsciiDoc if applicable
$ make sphinx # Sphinx docs specifically
=== Erlang.mk configuration
Default Erlang.mk settings are equivalent to adding to project's makefile
following lines:
[source,make]
SPHINX_FORMATS = html
SPHINX_SOURCE = doc
To change the location of Sphinx sources, you need to set `$(SPHINX_SOURCE)`
variable. 'conf.py' file should also be placed in that directory, unless you
specify `$(SPHINX_CONFDIR)`.
Variable `$(SPHINX_OPTS)` allows to provide options to `sphinx-build`, which
is particularly useful for `-D name=value` options. You can even forego
'doc/conf.py' file, using `-D name=value` in combination with `-C` option,
though you will need to manually call `make sphinx` or add `sphinx` target to
dependencies of `docs`.
`$(SPHINX_FORMATS)` variable lists formats to generate. By default only HTML
is generated, but it can also include man pages or LaTeX document for building
PDF. See
http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b[description of `-b` option]
for `sphinx-build` for list of known formats.
Formats are by default generated to a directory called after the format
('html' for HTML, 'man' for man pages, and so on). To change this behaviour
for specific format, you can set `$(sphinx_$(format)_output)` variable, e.g.
`$(sphinx_html_output)` for 'html' or `$(sphinx_man_output)` for 'man'.
There are also `$(sphinx_$(format)_opts)` variables for setting `sphinx-build`
options for a single format only.
=== Generating man pages
To generate man pages, you need to include `man` in `$(SPHINX_FORMATS)` in
your makefile and define `man_pages` option in 'doc/conf.py':
[source,python]
----
man_pages = [
('doc_name', 'page_name', 'Manpage Title', ['Page Author'], 1),
]
----
As http://www.sphinx-doc.org/en/stable/config.html#options-for-manual-page-output[Sphinx documentation]
says, the structure is following:
* 'doc_name' is the path to man page's source (relative `$(SPHINX_SOURCE)`),
without the '.rst' suffix
* 'page_name' is the name of resulting man page, which will be used as a base
for output file name and will be included in generated man page
* 'Manpage Title' is a short, one-line description, which will be included in
generated man page on a position that's used by `apropos` command
* 'Page Author' (or more of them) will be included in autogenerated 'AUTHOR'
section, and leaving this field empty disables generating 'AUTHOR' section
* '1' is the number of section of the man page
With the above configuration (and Erlang.mk defaults), 'doc/doc_name.rst' will
be used to generate 'man/page_name.1'.
NOTE: You probably want to include a link to the man page in other
documentation, possibly in 'doc/index.rst'.
|
