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:
Dmitry Ilyin
parent
2ace3ab436
commit
96987b967f
|
|
@ -30,3 +30,5 @@ nailgun/static/css/styles.css
|
|||
.DS_Store
|
||||
|
||||
*.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 " 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 " pdf to make PDF using rst2pdf"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
|
|
@ -83,17 +84,17 @@ qthelp:
|
|||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".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 "# assistant -collectionFile $(BUILDDIR)/qthelp/scaffold.qhc"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/fuel.qhc"
|
||||
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/scaffold"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/scaffold"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/fuel"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/fuel"
|
||||
@echo "# devhelp"
|
||||
|
||||
epub:
|
||||
|
|
@ -114,6 +115,11 @@ latexpdf:
|
|||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@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:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
|
|
|
|||
|
|
@ -37,11 +37,11 @@ extensions += ['rst2pdf.pdfbuilder']
|
|||
pdf_documents = [
|
||||
(master_doc, project, project, copyright),
|
||||
]
|
||||
pdf_stylesheets = ['sphinx', 'kerning', 'a4', 'en']
|
||||
pdf_language = "en"
|
||||
pdf_stylesheets = ['sphinx', 'kerning', 'a4']
|
||||
pdf_language = "en_US"
|
||||
# Mode for literal blocks wider than the frame. Can be
|
||||
# overflow, shrink or truncate
|
||||
#pdf_fit_mode = "shrink"
|
||||
pdf_fit_mode = "shrink"
|
||||
|
||||
# Section level that forces a break 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
|
||||
# at the end.
|
||||
pdf_inline_footnotes = True
|
||||
pdf_inline_footnotes = False
|
||||
|
||||
# verbosity level. 0 1 or 2
|
||||
pdf_verbosity = 0
|
||||
|
|
@ -92,7 +92,7 @@ pdf_use_coverpage = True
|
|||
pdf_use_toc = True
|
||||
|
||||
# How many levels deep should the table of contents be?
|
||||
pdf_toc_depth = 2
|
||||
pdf_toc_depth = 3
|
||||
|
||||
# Add section number to section references
|
||||
pdf_use_numbered_links = False
|
||||
|
|
|
|||
30
docs/conf.py
30
docs/conf.py
|
|
@ -1,7 +1,6 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# scaffold documentation build configuration file, created by
|
||||
# sphinx-quickstart on Tue Sep 25 14:02:29 2012.
|
||||
# fuel documentation build configuration file
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its containing
|
||||
# dir.
|
||||
|
|
@ -53,7 +52,7 @@ master_doc = 'index'
|
|||
|
||||
# General information about the project.
|
||||
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
|
||||
# |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
|
||||
# for a list of supported languages.
|
||||
#language = None
|
||||
language = 'en'
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
|
|
@ -177,28 +176,31 @@ html_theme_path = ["_templates"]
|
|||
#html_file_suffix = None
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'scaffolddoc'
|
||||
htmlhelp_basename = 'fuel-doc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output -------------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#'papersize': 'letterpaper',
|
||||
'papersize': 'a4paper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#'pointsize': '10pt',
|
||||
'pointsize': '12pt',
|
||||
|
||||
# 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
|
||||
# (source start file, target name, title, author, documentclass
|
||||
# [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'scaffold.tex', u'scaffold Documentation',
|
||||
u'Mike Scherbakov', 'manual'),
|
||||
('index', 'fuel.tex', u'Fuel Documentation', u'Mike Scherbakov', 'manual'),
|
||||
]
|
||||
|
||||
# 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
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
('index', 'scaffold', u'scaffold Documentation',
|
||||
[u'Mike Scherbakov'], 1)
|
||||
('index', 'fuel', u'Fuel Documentation', [u'Mike Scherbakov'], 1)
|
||||
]
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
|
|
@ -241,9 +242,8 @@ man_pages = [
|
|||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [(
|
||||
'index', 'scaffold', u'scaffold Documentation',
|
||||
u'Mike Scherbakov', 'scaffold', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
'index', 'fuel', u'Fuel Documentation', u'Mike Scherbakov',
|
||||
'fuel', 'OpenStack Installer', 'Miscellaneous'),
|
||||
]
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Development Documentation
|
|||
=========================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
:numbered:
|
||||
|
||||
develop/logical_arch
|
||||
|
|
|
|||
|
|
@ -340,15 +340,91 @@ package in Ubuntu is outdated)::
|
|||
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
|
||||
make help
|
||||
make html
|
||||
|
||||
You will also need to install Java and 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.
|
||||
There is a helper script **build-docs.sh**. It can perform
|
||||
all the required steps automatically. The script can build documentation
|
||||
in required format.
|
||||
::
|
||||
|
||||
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::
|
||||
:maxdepth: 3
|
||||
:maxdepth: 4
|
||||
:numbered:
|
||||
|
||||
develop
|
||||
user
|
||||
|
|
|
|||
|
|
@ -100,9 +100,9 @@ if "%1" == "qthelp" (
|
|||
echo.
|
||||
echo.Build finished; now you can run "qcollectiongenerator" with the ^
|
||||
.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.^> assistant -collectionFile %BUILDDIR%\qthelp\scaffold.ghc
|
||||
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\fuel.ghc
|
||||
goto end
|
||||
)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue