btrfs-ioctl.rst was laid out like it should be a man page, including
having a section number, but it wasn't getting installed because there
was not enough content.
Pull-request: #892
Signed-off-by: Mark Harmstone <maharmstone@fb.com>
Signed-off-by: David Sterba <dsterba@suse.com>
Feature from https://github.com/sphinx-doc/sphinx/pull/2064 enable
navigation to be able to navigate documentation using the arrow keys.
Pull-request: #754
Author: Martin <spleefer90@gmail.com>
Signed-off-by: David Sterba <dsterba@suse.com>
Sphinx/RST does not(?) have native support for cross references to
labels in specific documents (doc, ref but not both at the same time),
also allowing duplicate labels. We have web and manual pages and to
share the same text there are common files included from each, defining
labels. This leads to warnings and clicking the links ends up in the
included document (like ch-volume-management-intro.rst) instead of the
parent.
As a last resort, implement own role that does the doc and ref in one
go. A special directive is used to define a label that is expected
to be duplicate (but otherwise it's an ordinary label) and this gets rid
of the warning too.
Signed-off-by: David Sterba <dsterba@suse.com>
The copyright config variable can be used for a real copyright but we
don't have that for the manual pages and it was a stub. The date of page
generation time is added to the page anyway.
Signed-off-by: David Sterba <dsterba@suse.com>
There was a workaround for asciidoc/xmlto build because page btrfs.5 and
btrfs.8 used the same intermediate file. To avoid clash for the section
5 page it is part of the name, this is still needed, but for sphinx we
can use the final name as it will get the right suffix. This affects
only the generated manual pages.
Signed-off-by: David Sterba <dsterba@suse.com>
Update sphinx build so that by default it now builds the manual pages,
in quiet mode. 'make html' builds the html, other sphinx targets are
available, see 'make help'. Installation now works as well.
Note: sphinx is still conditional and must be selected by
ASCIIDOOC_TOOL=sphinx ./configure
Signed-off-by: David Sterba <dsterba@suse.com>
All long command line options in the html target render as a single
character which is confusing and wrong as we expect that to be '--'.
Disable it.
Signed-off-by: David Sterba <dsterba@suse.com>
The asciidoc format needs to be tweaked but otherwise is basically the
same. Changes:
- bold text is ** **
- italics is * *
- NOTE is directive .. note
- definition list is simple indented block after the term
- section NAME in the manual page is generated from date in
conf.py:man_pages
- new page has to be added to the index
To do:
- references to other manual pages, will be RST native linking once all
the pages are converted
The output is in Documentation/_build/man and the format is visually not
much different from what is generated by asciidoc.
Signed-off-by: David Sterba <dsterba@suse.com>
Add basic config and build files for sphinx. The long term plan is to
convert all asciidoc sources to ReST and host majority of wiki contents,
and maybe more.
Build:
$ cd Documentation/
$ make -f Makefile.sphinx html
The result is in Documentation/_build/html.
Signed-off-by: David Sterba <dsterba@suse.com>
