Rewrite how to build the documentation
And add build script Add rst2pdf builder Many other fixes Closes-Bug: 1282556 Change-Id: I4083495db0b04b8751a397dffd06941a214722c1
This commit is contained in:
parent
2ace3ab436
commit
96987b967f
|
@ -30,3 +30,5 @@ nailgun/static/css/styles.css
|
||||||
.DS_Store
|
.DS_Store
|
||||||
|
|
||||||
*.egg-info
|
*.egg-info
|
||||||
|
|
||||||
|
fuel-web-venv
|
||||||
|
|
|
@ -0,0 +1,233 @@
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
# config
|
||||||
|
|
||||||
|
VENV='fuel-web-venv'
|
||||||
|
VIEW='0'
|
||||||
|
NOINSTALL='0'
|
||||||
|
HTML='docs/_build/html/index.html'
|
||||||
|
SINGLEHTML='docs/_build/singlehtml/index.html'
|
||||||
|
EPUB='docs/_build/epub/Fuel.epub'
|
||||||
|
LATEXPDF='docs/_build/latex/fuel.pdf'
|
||||||
|
PDF='docs/_build/pdf/Fuel.pdf'
|
||||||
|
|
||||||
|
# functions
|
||||||
|
|
||||||
|
check_if_debian() {
|
||||||
|
test -f '/etc/debian_version'
|
||||||
|
return $?
|
||||||
|
}
|
||||||
|
|
||||||
|
check_if_redhat() {
|
||||||
|
test -f '/etc/redhat-release'
|
||||||
|
return $?
|
||||||
|
}
|
||||||
|
|
||||||
|
check_java_present() {
|
||||||
|
which java 1>/dev/null 2>/dev/null
|
||||||
|
return $?
|
||||||
|
}
|
||||||
|
|
||||||
|
check_latex_present() {
|
||||||
|
which pdflatex 1>/dev/null 2>/dev/null
|
||||||
|
return $?
|
||||||
|
}
|
||||||
|
|
||||||
|
cd_to_dir() {
|
||||||
|
FILE="${0}"
|
||||||
|
DIR=`dirname "${FILE}"`
|
||||||
|
cd "${DIR}"
|
||||||
|
if [ $? -gt 0 ]; then
|
||||||
|
echo "Cannot cd to dir ${DIR}!"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
redhat_prepare_packages() {
|
||||||
|
# prepare postgresql utils and dev packages
|
||||||
|
# required to build psycopg Python pgsql library
|
||||||
|
sudo yum -y install postgresql postgresql-devel
|
||||||
|
|
||||||
|
# prepare python tools
|
||||||
|
sudo yum -y install python-devel make python-pip python-virtualenv
|
||||||
|
}
|
||||||
|
|
||||||
|
debian_prepare_packages() {
|
||||||
|
# prepare postgresql utils and dev packages
|
||||||
|
# required to build psycopg Python pgsql library
|
||||||
|
sudo apt-get -y install postgresql postgresql-server-dev-all
|
||||||
|
|
||||||
|
# prepare python tools
|
||||||
|
sudo apt-get -y install python-dev python-pip make python-virtualenv
|
||||||
|
}
|
||||||
|
|
||||||
|
install_java() {
|
||||||
|
if check_if_debian; then
|
||||||
|
sudo apt-get -y install default-jre
|
||||||
|
elif check_if_redhat; then
|
||||||
|
sudo yum -y install java
|
||||||
|
else
|
||||||
|
echo 'OS is not supported!'
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
prepare_packages() {
|
||||||
|
if check_if_debian; then
|
||||||
|
debian_prepare_packages
|
||||||
|
elif check_if_redhat; then
|
||||||
|
redhat_prepare_packages
|
||||||
|
else
|
||||||
|
echo 'OS is not supported!'
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
prepare_venv() {
|
||||||
|
# activate venv
|
||||||
|
virtualenv "${VENV}" # you can use any name instead of 'fuel'
|
||||||
|
. "${VENV}/bin/activate" # command selects the particular environment
|
||||||
|
# install dependencies
|
||||||
|
pip install ./shotgun # this fuel project is listed in setup.py requirements
|
||||||
|
pip install -r 'nailgun/test-requirements.txt'
|
||||||
|
}
|
||||||
|
|
||||||
|
download_plantuml() {
|
||||||
|
if ! [ -f 'docs/plantuml.jar' ]; then
|
||||||
|
wget 'http://downloads.sourceforge.net/project/plantuml/plantuml.jar' -O 'docs/plantuml.jar'
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
view_file() {
|
||||||
|
if [ "`uname`" = "Darwin" ]; then
|
||||||
|
open "${1}"
|
||||||
|
elif [ "`uname`" = "Linux" ]; then
|
||||||
|
xdg-open "${1}"
|
||||||
|
else
|
||||||
|
echo 'OS is not supported!'
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
build_html() {
|
||||||
|
make -C docs html
|
||||||
|
if [ "${VIEW}" = '1' ]; then
|
||||||
|
view_file "${HTML}"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
build_singlehtml() {
|
||||||
|
make -C docs singlehtml
|
||||||
|
if [ "${VIEW}" = '1' ]; then
|
||||||
|
view_file "${SINGLEHTML}"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
build_latexpdf() {
|
||||||
|
check_latex_present
|
||||||
|
if [ $? -gt 0 ]; then
|
||||||
|
echo 'You need to install LaTeX if you want to build PDF!'
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
make -C docs latexpdf
|
||||||
|
if [ "${VIEW}" = '1' ]; then
|
||||||
|
view_file "${LATEXPDF}"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
build_epub() {
|
||||||
|
make -C docs epub
|
||||||
|
if [ "${VIEW}" = '1' ]; then
|
||||||
|
view_file "${EPUB}"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
build_pdf() {
|
||||||
|
make -C docs pdf
|
||||||
|
if [ "${VIEW}" = '1' ]; then
|
||||||
|
view_file "${PDF}"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
clear_build() {
|
||||||
|
make -C docs clean
|
||||||
|
}
|
||||||
|
|
||||||
|
show_help() {
|
||||||
|
cat <<EOF
|
||||||
|
Documentation build helper
|
||||||
|
-o - Open generated documentation after build
|
||||||
|
-c - Clear the build directory
|
||||||
|
-n - Don't try to install any packages
|
||||||
|
-f - Documentation format [html,signlehtml,pdf,latexpdf,epub]
|
||||||
|
EOF
|
||||||
|
}
|
||||||
|
|
||||||
|
# MAIN
|
||||||
|
|
||||||
|
while getopts ":onhcf:" opt; do
|
||||||
|
case $opt in
|
||||||
|
o)
|
||||||
|
VIEW='1'
|
||||||
|
;;
|
||||||
|
n)
|
||||||
|
NOINSTALL='1'
|
||||||
|
;;
|
||||||
|
h)
|
||||||
|
show_help
|
||||||
|
exit 0
|
||||||
|
;;
|
||||||
|
c)
|
||||||
|
clear_build
|
||||||
|
exit 0
|
||||||
|
;;
|
||||||
|
f)
|
||||||
|
FORMAT="${OPTARG}"
|
||||||
|
;;
|
||||||
|
\?)
|
||||||
|
echo "Invalid option: -$OPTARG" >&2
|
||||||
|
show_help
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
cd_to_dir
|
||||||
|
|
||||||
|
check_java_present
|
||||||
|
if [ $? -gt 0 ]; then
|
||||||
|
install_java
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [ "${NOINSTALL}" = '0' ]; then
|
||||||
|
prepare_packages
|
||||||
|
fi
|
||||||
|
|
||||||
|
prepare_venv
|
||||||
|
download_plantuml
|
||||||
|
|
||||||
|
if [ "${FORMAT}" = '' ]; then
|
||||||
|
FORMAT='html'
|
||||||
|
fi
|
||||||
|
|
||||||
|
case "${FORMAT}" in
|
||||||
|
html)
|
||||||
|
build_html
|
||||||
|
;;
|
||||||
|
singlehtml)
|
||||||
|
build_singlehtml
|
||||||
|
;;
|
||||||
|
pdf)
|
||||||
|
build_pdf
|
||||||
|
;;
|
||||||
|
latexpdf)
|
||||||
|
build_latexpdf
|
||||||
|
;;
|
||||||
|
epub)
|
||||||
|
build_epub
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
echo "Format ${FORMAT} is not supported!"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
|
@ -31,6 +31,7 @@ help:
|
||||||
@echo " epub to make an epub"
|
@echo " epub to make an epub"
|
||||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||||
|
@echo " pdf to make PDF using rst2pdf"
|
||||||
@echo " text to make text files"
|
@echo " text to make text files"
|
||||||
@echo " man to make manual pages"
|
@echo " man to make manual pages"
|
||||||
@echo " texinfo to make Texinfo files"
|
@echo " texinfo to make Texinfo files"
|
||||||
|
@ -83,17 +84,17 @@ qthelp:
|
||||||
@echo
|
@echo
|
||||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/scaffold.qhcp"
|
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/fuel.qhcp"
|
||||||
@echo "To view the help file:"
|
@echo "To view the help file:"
|
||||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/scaffold.qhc"
|
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/fuel.qhc"
|
||||||
|
|
||||||
devhelp:
|
devhelp:
|
||||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||||
@echo
|
@echo
|
||||||
@echo "Build finished."
|
@echo "Build finished."
|
||||||
@echo "To view the help file:"
|
@echo "To view the help file:"
|
||||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/scaffold"
|
@echo "# mkdir -p $$HOME/.local/share/devhelp/fuel"
|
||||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/scaffold"
|
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/fuel"
|
||||||
@echo "# devhelp"
|
@echo "# devhelp"
|
||||||
|
|
||||||
epub:
|
epub:
|
||||||
|
@ -114,6 +115,11 @@ latexpdf:
|
||||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||||
|
|
||||||
|
pdf:
|
||||||
|
$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; the PDF file is in $(BUILDDIR)/pdf."
|
||||||
|
|
||||||
text:
|
text:
|
||||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||||
@echo
|
@echo
|
||||||
|
|
|
@ -37,11 +37,11 @@ extensions += ['rst2pdf.pdfbuilder']
|
||||||
pdf_documents = [
|
pdf_documents = [
|
||||||
(master_doc, project, project, copyright),
|
(master_doc, project, project, copyright),
|
||||||
]
|
]
|
||||||
pdf_stylesheets = ['sphinx', 'kerning', 'a4', 'en']
|
pdf_stylesheets = ['sphinx', 'kerning', 'a4']
|
||||||
pdf_language = "en"
|
pdf_language = "en_US"
|
||||||
# Mode for literal blocks wider than the frame. Can be
|
# Mode for literal blocks wider than the frame. Can be
|
||||||
# overflow, shrink or truncate
|
# overflow, shrink or truncate
|
||||||
#pdf_fit_mode = "shrink"
|
pdf_fit_mode = "shrink"
|
||||||
|
|
||||||
# Section level that forces a break page.
|
# Section level that forces a break page.
|
||||||
# For example: 1 means top-level sections start in a new page
|
# For example: 1 means top-level sections start in a new page
|
||||||
|
@ -54,7 +54,7 @@ pdf_breakside = 'any'
|
||||||
|
|
||||||
# Insert footnotes where they are defined instead of
|
# Insert footnotes where they are defined instead of
|
||||||
# at the end.
|
# at the end.
|
||||||
pdf_inline_footnotes = True
|
pdf_inline_footnotes = False
|
||||||
|
|
||||||
# verbosity level. 0 1 or 2
|
# verbosity level. 0 1 or 2
|
||||||
pdf_verbosity = 0
|
pdf_verbosity = 0
|
||||||
|
@ -92,7 +92,7 @@ pdf_use_coverpage = True
|
||||||
pdf_use_toc = True
|
pdf_use_toc = True
|
||||||
|
|
||||||
# How many levels deep should the table of contents be?
|
# How many levels deep should the table of contents be?
|
||||||
pdf_toc_depth = 2
|
pdf_toc_depth = 3
|
||||||
|
|
||||||
# Add section number to section references
|
# Add section number to section references
|
||||||
pdf_use_numbered_links = False
|
pdf_use_numbered_links = False
|
||||||
|
|
30
docs/conf.py
30
docs/conf.py
|
@ -1,7 +1,6 @@
|
||||||
# -*- coding: utf-8 -*-
|
# -*- coding: utf-8 -*-
|
||||||
#
|
#
|
||||||
# scaffold documentation build configuration file, created by
|
# fuel documentation build configuration file
|
||||||
# sphinx-quickstart on Tue Sep 25 14:02:29 2012.
|
|
||||||
#
|
#
|
||||||
# This file is execfile()d with the current directory set to its containing
|
# This file is execfile()d with the current directory set to its containing
|
||||||
# dir.
|
# dir.
|
||||||
|
@ -53,7 +52,7 @@ master_doc = 'index'
|
||||||
|
|
||||||
# General information about the project.
|
# General information about the project.
|
||||||
project = u'Fuel'
|
project = u'Fuel'
|
||||||
copyright = u'2012, Mirantis'
|
copyright = u'2012-2014, Mirantis'
|
||||||
|
|
||||||
# The version info for the project you're documenting, acts as replacement for
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
# |version| and |release|, also used in various other places throughout the
|
# |version| and |release|, also used in various other places throughout the
|
||||||
|
@ -66,7 +65,7 @@ release = ''
|
||||||
|
|
||||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
# for a list of supported languages.
|
# for a list of supported languages.
|
||||||
#language = None
|
language = 'en'
|
||||||
|
|
||||||
# There are two options for replacing |today|: either, you set today to some
|
# There are two options for replacing |today|: either, you set today to some
|
||||||
# non-false value, then it is used:
|
# non-false value, then it is used:
|
||||||
|
@ -177,28 +176,31 @@ html_theme_path = ["_templates"]
|
||||||
#html_file_suffix = None
|
#html_file_suffix = None
|
||||||
|
|
||||||
# Output file base name for HTML help builder.
|
# Output file base name for HTML help builder.
|
||||||
htmlhelp_basename = 'scaffolddoc'
|
htmlhelp_basename = 'fuel-doc'
|
||||||
|
|
||||||
|
|
||||||
# -- Options for LaTeX output -------------------------------------------------
|
# -- Options for LaTeX output -------------------------------------------------
|
||||||
|
|
||||||
latex_elements = {
|
latex_elements = {
|
||||||
# The paper size ('letterpaper' or 'a4paper').
|
# The paper size ('letterpaper' or 'a4paper').
|
||||||
#'papersize': 'letterpaper',
|
'papersize': 'a4paper',
|
||||||
|
|
||||||
# The font size ('10pt', '11pt' or '12pt').
|
# The font size ('10pt', '11pt' or '12pt').
|
||||||
#'pointsize': '10pt',
|
'pointsize': '12pt',
|
||||||
|
|
||||||
# Additional stuff for the LaTeX preamble.
|
# Additional stuff for the LaTeX preamble.
|
||||||
#'preamble': '',
|
'preamble': '''
|
||||||
|
\setcounter{tocdepth}{3}
|
||||||
|
\usepackage{tocbibind}
|
||||||
|
\pagenumbering{arabic}
|
||||||
|
'''
|
||||||
}
|
}
|
||||||
|
|
||||||
# Grouping the document tree into LaTeX files. List of tuples
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
# (source start file, target name, title, author, documentclass
|
# (source start file, target name, title, author, documentclass
|
||||||
# [howto/manual]).
|
# [howto/manual]).
|
||||||
latex_documents = [
|
latex_documents = [
|
||||||
('index', 'scaffold.tex', u'scaffold Documentation',
|
('index', 'fuel.tex', u'Fuel Documentation', u'Mike Scherbakov', 'manual'),
|
||||||
u'Mike Scherbakov', 'manual'),
|
|
||||||
]
|
]
|
||||||
|
|
||||||
# The name of an image file (relative to this directory) to place at the top of
|
# The name of an image file (relative to this directory) to place at the top of
|
||||||
|
@ -227,8 +229,7 @@ latex_documents = [
|
||||||
# One entry per manual page. List of tuples
|
# One entry per manual page. List of tuples
|
||||||
# (source start file, name, description, authors, manual section).
|
# (source start file, name, description, authors, manual section).
|
||||||
man_pages = [
|
man_pages = [
|
||||||
('index', 'scaffold', u'scaffold Documentation',
|
('index', 'fuel', u'Fuel Documentation', [u'Mike Scherbakov'], 1)
|
||||||
[u'Mike Scherbakov'], 1)
|
|
||||||
]
|
]
|
||||||
|
|
||||||
# If true, show URL addresses after external links.
|
# If true, show URL addresses after external links.
|
||||||
|
@ -241,9 +242,8 @@ man_pages = [
|
||||||
# (source start file, target name, title, author,
|
# (source start file, target name, title, author,
|
||||||
# dir menu entry, description, category)
|
# dir menu entry, description, category)
|
||||||
texinfo_documents = [(
|
texinfo_documents = [(
|
||||||
'index', 'scaffold', u'scaffold Documentation',
|
'index', 'fuel', u'Fuel Documentation', u'Mike Scherbakov',
|
||||||
u'Mike Scherbakov', 'scaffold', 'One line description of project.',
|
'fuel', 'OpenStack Installer', 'Miscellaneous'),
|
||||||
'Miscellaneous'),
|
|
||||||
]
|
]
|
||||||
|
|
||||||
# Documents to append as an appendix to all manuals.
|
# Documents to append as an appendix to all manuals.
|
||||||
|
|
|
@ -4,7 +4,7 @@ Development Documentation
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 3
|
||||||
:numbered:
|
:numbered:
|
||||||
|
|
||||||
develop/logical_arch
|
develop/logical_arch
|
||||||
|
|
|
@ -340,15 +340,91 @@ package in Ubuntu is outdated)::
|
||||||
Building Documentation
|
Building Documentation
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
#. You will need to follow steps from :ref:`nailgun_dependencies` section to build documentation.
|
You should prepare your build environment before you can build
|
||||||
|
this documentation. First you must install Java, using the
|
||||||
|
appropriate procedure for your operating system.
|
||||||
|
|
||||||
#. Look at the list of available formats and generate the one you need::
|
Java is needed to use PlantUML to automatically generate UML diagrams
|
||||||
|
from the source. You can also use `PlantUML Server
|
||||||
|
<http://www.plantuml.com/plantuml/>`_ for a quick preview of your
|
||||||
|
diagrams and language documentation.
|
||||||
|
|
||||||
|
Then you need to install all the packages required for creating of
|
||||||
|
the Python virtual environment and dependencies installation.
|
||||||
|
::
|
||||||
|
|
||||||
|
sudo apt-get install make postgresql postgresql-server-dev-9.1
|
||||||
|
sudo apt-get install python-dev python-pip python-virtualenv
|
||||||
|
|
||||||
|
Now you can create the virtual environment and activate it.
|
||||||
|
::
|
||||||
|
|
||||||
|
virtualenv fuel-web-venv
|
||||||
|
. virtualenv/bin/activate
|
||||||
|
|
||||||
|
And then install the dependencies.
|
||||||
|
::
|
||||||
|
|
||||||
|
pip install ./shotgun
|
||||||
|
pip install -r nailgun/test-requirements.txt
|
||||||
|
|
||||||
|
Now you can look at the list of available formats and generate
|
||||||
|
the one you need:
|
||||||
|
::
|
||||||
|
|
||||||
cd docs
|
cd docs
|
||||||
make help
|
make help
|
||||||
make html
|
make html
|
||||||
|
|
||||||
You will also need to install Java and PlantUML to automatically
|
There is a helper script **build-docs.sh**. It can perform
|
||||||
generate UML diagrams from the source. You can also use `PlantUML Server
|
all the required steps automatically. The script can build documentation
|
||||||
<http://www.plantuml.com/plantuml/>`_ for a quick preview of your
|
in required format.
|
||||||
diagrams.
|
::
|
||||||
|
|
||||||
|
Documentation build helper
|
||||||
|
-o - Open generated documentation after build
|
||||||
|
-c - Clear the build directory
|
||||||
|
-n - Don't install any packages
|
||||||
|
-f - Documentation format [html,signlehtml,latexpdf,pdf,epub]
|
||||||
|
|
||||||
|
For example, if you want to build HTML documentation you can just
|
||||||
|
use this thispt like this:
|
||||||
|
::
|
||||||
|
|
||||||
|
./build-docs.sh -f html -o
|
||||||
|
|
||||||
|
It will create virtualenv, install the required dependencies and
|
||||||
|
build the documentation in HTML format. It will also open the
|
||||||
|
documentation with your default browser.
|
||||||
|
|
||||||
|
If you don't want to install all the dependencies and you are not
|
||||||
|
interested in building automatic API documentation there is an easy
|
||||||
|
way to do it.
|
||||||
|
|
||||||
|
First remove autodoc modules from extensions section of **conf.py**
|
||||||
|
file in the **docs** directory. This section should be like this:
|
||||||
|
::
|
||||||
|
|
||||||
|
extensions = [
|
||||||
|
'rst2pdf.pdfbuilder',
|
||||||
|
'sphinxcontrib.plantuml',
|
||||||
|
]
|
||||||
|
|
||||||
|
Then remove **develop/api_doc.rst** file and reference to it from
|
||||||
|
**develop.rst** index.
|
||||||
|
|
||||||
|
Now you can build documentation as usual using make command.
|
||||||
|
This method can be useful if you want to make some corrections to
|
||||||
|
text and see the results without building the entire environment.
|
||||||
|
The only Python packages you need are Sphinx packages:
|
||||||
|
::
|
||||||
|
|
||||||
|
Sphinx
|
||||||
|
sphinxcontrib-actdiag
|
||||||
|
sphinxcontrib-blockdiag
|
||||||
|
sphinxcontrib-nwdiag
|
||||||
|
sphinxcontrib-plantuml
|
||||||
|
sphinxcontrib-seqdiag
|
||||||
|
|
||||||
|
Just don't forget to rollback all these changes before you commit your
|
||||||
|
corrections.
|
||||||
|
|
|
@ -4,7 +4,8 @@ Table of contents
|
||||||
=================
|
=================
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 3
|
:maxdepth: 4
|
||||||
|
:numbered:
|
||||||
|
|
||||||
develop
|
develop
|
||||||
user
|
user
|
||||||
|
|
|
@ -100,9 +100,9 @@ if "%1" == "qthelp" (
|
||||||
echo.
|
echo.
|
||||||
echo.Build finished; now you can run "qcollectiongenerator" with the ^
|
echo.Build finished; now you can run "qcollectiongenerator" with the ^
|
||||||
.qhcp project file in %BUILDDIR%/qthelp, like this:
|
.qhcp project file in %BUILDDIR%/qthelp, like this:
|
||||||
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\scaffold.qhcp
|
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\fuel.qhcp
|
||||||
echo.To view the help file:
|
echo.To view the help file:
|
||||||
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\scaffold.ghc
|
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\fuel.ghc
|
||||||
goto end
|
goto end
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue