diff --git a/.gitignore b/.gitignore index 05b9f1ad3b..59c3e66ce3 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,5 @@ nailgun/static/css/styles.css .DS_Store *.egg-info + +fuel-web-venv diff --git a/build_docs.sh b/build_docs.sh new file mode 100755 index 0000000000..24decff7fc --- /dev/null +++ b/build_docs.sh @@ -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 <&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 diff --git a/docs/Makefile b/docs/Makefile index e5a407af0c..416a866102 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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 diff --git a/docs/common_conf.py b/docs/common_conf.py index a45b6de0ed..c3cc9d1ad4 100644 --- a/docs/common_conf.py +++ b/docs/common_conf.py @@ -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 diff --git a/docs/conf.py b/docs/conf.py index 2387ef28de..78f735c33a 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/develop.rst b/docs/develop.rst index f83e1ebefd..6a726d2662 100644 --- a/docs/develop.rst +++ b/docs/develop.rst @@ -4,7 +4,7 @@ Development Documentation ========================= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :numbered: develop/logical_arch diff --git a/docs/develop/env.rst b/docs/develop/env.rst index e28d1f0b28..69b760f4d9 100644 --- a/docs/develop/env.rst +++ b/docs/develop/env.rst @@ -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 +`_ 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 -`_ 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. diff --git a/docs/index.rst b/docs/index.rst index b4a5bbcdba..efe7590f09 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,8 @@ Table of contents ================= .. toctree:: - :maxdepth: 3 + :maxdepth: 4 + :numbered: develop user diff --git a/docs/make.bat b/docs/make.bat index fe9c00afce..34e9cb2e85 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -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 )