diff options
Diffstat (limited to 'resources/tools/doc_gen')
| -rw-r--r-- | resources/tools/doc_gen/README.rst | 116 | ||||
| -rwxr-xr-x | resources/tools/doc_gen/gen_rst.py | 256 | ||||
| -rwxr-xr-x | resources/tools/doc_gen/run_doc.sh | 45 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/Makefile | 225 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/conf.py | 346 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/fdio_logo.png | bin | 0 -> 3708 bytes | |||
| -rw-r--r-- | resources/tools/doc_gen/src/index.rst | 78 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/requirements.txt | 3 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/resources.libraries.python.rst | 3 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/resources.libraries.robot.rst | 3 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/tests.func.rst | 3 | ||||
| -rw-r--r-- | resources/tools/doc_gen/src/tests.perf.rst | 3 |
12 files changed, 1081 insertions, 0 deletions
diff --git a/resources/tools/doc_gen/README.rst b/resources/tools/doc_gen/README.rst new file mode 100644 index 0000000000..57771e80d5 --- /dev/null +++ b/resources/tools/doc_gen/README.rst @@ -0,0 +1,116 @@ +How to generate documentation +============================= + + +Requirements +------------ + +This tool uses Sphinx and read-the-doc theme. All required modules are listed in +src/requirements.txt. These requirements are addition to CSIT requirements +defined in requirements.txt. + +The generated documentation needs Java script to be fully functional. + +The generated documentation is in the directory _build. + + +How to generate documentation +----------------------------- + + - pull the last changes from git + - run: ./run_doc.sh + + +What is documented +------------------ + +All modules which are in these directories are documented: + - resources/libraries/python + - resources/libraries/robot + - tests + +If you add / remove / rename a module or directory to one of these +directories, nothing is needed to be done. + + +How to add or change info in generated documentation +---------------------------------------------------- + +There are templates for + - index + - Python library documentation + - Robot library documentation + - Functional tests documentation + - Performance tests documenation +in src/ directory. + +You can add information you want at the beginning of the file, generated +documentation will be appended at the end of these files. + +See index.rst for example. The information there was copy&pasted from fd.io + + +How to document code for perfect results +---------------------------------------- + +Follow PEP8 and guidelines on wiki https://wiki.fd.io/view/CSIT/Documentation + +This is the best practice when we use Sphinx: + +Python code ++++++++++++ + +.. code:: python + + """Module description, start with one-short-sentence-description. + + Add more descriptive text. + + You can add a list (there must be an empty line): + + - item, + - second item. + + or numbered list (there also must be an empty line): + + #. The first item, + #. The second item. + + """ + + class ExampleClass(BaseClass): + """Start with one-short-sentence-description. + + Add more descriptive text. + """ + + def example_function(parameter, param_def="def"): + """Start with one-short-sentence-description. + + Add more descriptive text, and / or example. + + :Example: + + followed by a blank line! + + You can use also: + .. seealso:: blabla + .. warnings:: blabla + .. note:: blabla + .. todo:: blabla + + :param parameter: The first parameter. Capital letter at the + beginning, full stop at the end, 80 characters long lines. + :param param_def: The parameter with default value. + :type param: str, int, dict, ... Use python data types. + :type param_def: str + :raises: ValueError - describe when this exception is raised. + :returns: Nice string. + :rtype: str + """ + + +Robot code +++++++++++ + +TBD diff --git a/resources/tools/doc_gen/gen_rst.py b/resources/tools/doc_gen/gen_rst.py new file mode 100755 index 0000000000..8f239d0951 --- /dev/null +++ b/resources/tools/doc_gen/gen_rst.py @@ -0,0 +1,256 @@ +#!/usr/bin/python + +# Copyright (c) 2016 Cisco and/or its affiliates. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +from os import walk, listdir +from os.path import isfile, isdir, join, getsize + +# Temporary working directory. It is created and deleted by run_doc.sh +WORKING_DIR = "tmp" + +# Directory with resources to be documented. +RESOURCES_DIR = "resources" + +# Directory with libraries (python, robot) to be documented. +LIB_DIR = "libraries" + +# Directory with tests (func, perf) to be documented. +TESTS_DIR = "tests" + +PY_EXT = ".py" +RF_EXT = ".robot" + +PATH_PY_LIBS = join(WORKING_DIR, RESOURCES_DIR, LIB_DIR, "python") +PATH_RF_LIBS = join(WORKING_DIR, RESOURCES_DIR, LIB_DIR, "robot") +PATH_TESTS = join(WORKING_DIR, TESTS_DIR) + +# Sections in rst files +rst_toc = """ +.. toctree:: +""" + +rst_py_module = """ +.. automodule:: {}.{} + :members: + :undoc-members: + :show-inheritance: +""" + +rst_rf_keywords = """ +.. robot-keywords:: + :source: {} +""" + +rst_rf_tests = """ +.. robot-tests:: + :source: {} +""" + + +def get_files(path, extension): + """Generates the list of files to process. + + :param path: Path to files. + :param extension: Extension of files to process. If it is the empty string, + all files will be processed. + :type path: str + :type extension: str + :returns: List of files to process. + :rtype: list + """ + + file_list = list() + for root, dirs, files in walk(path): + for filename in files: + if extension: + if filename.endswith(extension): + file_list.append(join(root, filename)) + else: + file_list.append(join(root, filename)) + + return file_list + + +def create_file_name(path, start): + """Create the name of rst file. + + Example: + resources.libraries.python.honeycomb.rst + tests.perf.rst + + :param path: Path to a module to be documented. + :param start: The first directory in path which is used in the file name. + :type path: str + :type start: str + :returns: File name. + :rtype: str + """ + dir_list = path.split('/') + start_index = dir_list.index(start) + return ".".join(dir_list[start_index:-1]) + ".rst" + + +def create_rst_file_names_set(files, start): + """Generate a set of unique rst file names. + + :param files: List of all files to be documented with path beginning in the + working directory. + :param start: The first directory in path which is used in the file name. + :type files: list + :type start: str + :returns: Set of unique rst file names. + :rtype: set + """ + file_names = set() + for file in files: + file_names.add(create_file_name(file, start)) + return file_names + + +def scan_dir(path): + """Create a list of files and directories in the given directory. + + :param path: Path to the directory. + :type path: str + :returns: List of directories and list of files sorted in alphabetical + order. + :rtype: tuple of two lists + """ + files = list() + dirs = list() + items = listdir(path) + for item in items: + if isfile(join(path, item)) and "__init__" not in item: + files.append(item) + elif isdir(join(path, item)): + dirs.append(item) + return sorted(dirs), sorted(files) + + +def write_toc(fh, path, dirs): + """Write a table of contents to given rst file. + + :param fh: File handler of the rst file. + :param path: Path to package. + :param dirs: List of directories to be included in ToC. + :type fh: file + :type path: str + :type dirs: list + """ + fh.write(rst_toc) + for dir in dirs: + fh.write(" {}.{}\n".format('.'.join(path), dir)) + + +def write_module_title(fh, module_name): + """Write the module title to the given rst file. The title will be on the + second level. + + :param fh: File handler of the rst file. + :param module_name: The name of module used for title. + :type fh: file + :type module_name: str + """ + title = "{} module".format(module_name) + fh.write("\n{}\n{}\n".format(title, '-' * len(title))) + + +def generate_py_rst_files(): + """Generate all rst files for all python modules.""" + + py_libs = get_files(PATH_PY_LIBS, PY_EXT) + file_names = create_rst_file_names_set(py_libs, RESOURCES_DIR) + + for file_name in file_names: + path = join(WORKING_DIR, *file_name.split('.')[:-1]) + dirs, files = scan_dir(path) + + full_path = join(WORKING_DIR, file_name) + with open(full_path, mode='a') as fh: + if getsize(full_path) == 0: + package = file_name.split('.')[-2] + fh.write("{} package\n".format(package)) + fh.write('=' * len("{} package".format(package))) + module_path = file_name.split('.')[:-1] + if dirs: + write_toc(fh, module_path, dirs) + for file in files: + module_name = file.split('.')[0] + write_module_title(fh, module_name) + fh.write(rst_py_module.format('.'.join(module_path), module_name)) + + +def generate_rf_rst_files(file_names, incl_tests=True, incl_keywords=True): + """Generate rst files for the given robot modules. + + :param file_names: List of file names to be included in the documentation + (rst files). + :param incl_tests: If true, tests will be included in the documentation. + :param incl_keywords: If true, keywords will be included in the + documentation. + :type file_names: set + :type incl_tests: bool + :type incl_keywords: bool + """ + + for file_name in file_names: + path = join(WORKING_DIR, *file_name.split('.')[:-1]) + dirs, files = scan_dir(path) + + full_path = join(WORKING_DIR, file_name) + with open(full_path, mode='a') as fh: + if getsize(full_path) == 0: + package = file_name.split('.')[-2] + fh.write("{} package\n".format(package)) + fh.write('=' * len("{} package".format(package)) + '\n') + module_path = file_name.split('.')[:-1] + if dirs: + write_toc(fh, module_path, dirs) + for file in files: + module_name = file.split('.')[0] + write_module_title(fh, module_name) + path = join(join(*module_path), module_name + RF_EXT) + if incl_tests: + fh.write(rst_rf_tests.format(path)) + if incl_keywords: + fh.write(rst_rf_keywords.format(path)) + + +def generate_kw_rst_files(): + """Generate all rst files for all robot modules with keywords in libraries + directory (no tests).""" + + rf_libs = get_files(PATH_RF_LIBS, RF_EXT) + file_names = create_rst_file_names_set(rf_libs, RESOURCES_DIR) + + generate_rf_rst_files(file_names, incl_tests=False) + + +def generate_tests_rst_files(): + """Generate all rst files for all robot modules with tests in tests + directory. Include also keywords defined in these modules.""" + + tests = get_files(PATH_TESTS, RF_EXT) + file_names = create_rst_file_names_set(tests, TESTS_DIR) + + generate_rf_rst_files(file_names) + + +if __name__ == '__main__': + + # Generate all rst files: + generate_py_rst_files() + generate_kw_rst_files() + generate_tests_rst_files() diff --git a/resources/tools/doc_gen/run_doc.sh b/resources/tools/doc_gen/run_doc.sh new file mode 100755 index 0000000000..bbb9940468 --- /dev/null +++ b/resources/tools/doc_gen/run_doc.sh @@ -0,0 +1,45 @@ +#!/bin/bash + +WORKING_DIR='tmp' +BUILD_DIR='_build' + +# Clean-up when finished: +trap 'rm -rf ${WORKING_DIR}; exit' EXIT +trap 'rm -rf ${WORKING_DIR}; exit' ERR + +# Remove the old build: +rm -rf ${BUILD_DIR} || true +rm -rf ${WORKING_DIR} || true + +# Create working directories +mkdir ${BUILD_DIR} +mkdir --parents ${WORKING_DIR}/resources/libraries/python/ +mkdir --parents ${WORKING_DIR}/resources/libraries/robot/ +mkdir --parents ${WORKING_DIR}/tests/ + +# Copy the Sphinx source files: +cp -r src/* ${WORKING_DIR}/ + +# Copy the source files to be processed: +rsync -a --include '*/' --include '*.py' --exclude '*' ../../../resources/libraries/python/ ${WORKING_DIR}/resources/libraries/python/ +cp ../../../resources/__init__.py ${WORKING_DIR}/resources/ +cp ../../../resources/libraries/__init__.py ${WORKING_DIR}/resources/libraries/ +rsync -a --include '*/' --include '*.robot' --exclude '*' ../../../resources/libraries/robot/ ${WORKING_DIR}/resources/libraries/robot/ +rsync -a --include '*/' --include '*.robot' --exclude '*' ../../../tests/ ${WORKING_DIR}/tests/ + +# Create virtual environment: +virtualenv ${WORKING_DIR}/env +. ${WORKING_DIR}/env/bin/activate + +# Install CSIT requirements: +pip install -r ../../../requirements.txt +# Install Sphinx: +pip install -r ${WORKING_DIR}/requirements.txt + +export PYTHONPATH=`pwd` + +# Generate rst files: +./gen_rst.py + +# Generate the documentation: +sphinx-build -vvv -b html ${WORKING_DIR}/ ${BUILD_DIR}/
\ No newline at end of file diff --git a/resources/tools/doc_gen/src/Makefile b/resources/tools/doc_gen/src/Makefile new file mode 100644 index 0000000000..dc34917ca9 --- /dev/null +++ b/resources/tools/doc_gen/src/Makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @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 " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/CSIT.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/CSIT.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/CSIT" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/CSIT" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/resources/tools/doc_gen/src/conf.py b/resources/tools/doc_gen/src/conf.py new file mode 100644 index 0000000000..e41868582e --- /dev/null +++ b/resources/tools/doc_gen/src/conf.py @@ -0,0 +1,346 @@ +# -*- coding: utf-8 -*- +# +# CSIT documentation build configuration file, created by +# sphinx-quickstart on Tue Nov 8 10:19:40 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinxcontrib_robotdoc', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'CSIT' +copyright = u'2016, CSIT' +author = u'CSIT' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'master' +# The full version, including alpha/beta/rc tags. +release = u'master' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ['env/lib/python2.7/site-packages/sphinx_rtd_theme'] + +# The name for this set of Sphinx documents. +# "<project> v<release> documentation" by default. +# +html_title = u'CSIT Documentation' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +html_short_title = u'CSIT' + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +html_logo = 'fdio_logo.png' + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = { +# +# } + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'csitdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'CSIT.tex', u'CSIT Documentation', + u'CSIT', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# +# latex_use_parts = False + +# If true, show page references after internal links. +# +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# If false, no module index is generated. +# +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'CSIT', u'CSIT Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'CSIT', u'CSIT Documentation', + author, 'CSIT', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False diff --git a/resources/tools/doc_gen/src/fdio_logo.png b/resources/tools/doc_gen/src/fdio_logo.png Binary files differnew file mode 100644 index 0000000000..3c362b2786 --- /dev/null +++ b/resources/tools/doc_gen/src/fdio_logo.png diff --git a/resources/tools/doc_gen/src/index.rst b/resources/tools/doc_gen/src/index.rst new file mode 100644 index 0000000000..b92ecd6bd4 --- /dev/null +++ b/resources/tools/doc_gen/src/index.rst @@ -0,0 +1,78 @@ +.. |csit| replace:: Continuous System Integration and Testing + + +|csit| Description +================== + +#. Development of software code for fully automated VPP code testing, functionality, performance, regression and new functions. +#. Execution of CSIT test suites on VPP code running on LF FD.io virtual and physical compute environments. +#. Integration with FD.io continuous integration systems (Gerrit, Jenkins and such). +#. Identified existing FD.io project dependencies and interactions: + - vpp - Vector Packet Processing. + - honeycomb - Honeycomb Agent for management plane testing. + - ci-management - Management repo for Jenkins Job Builder, script and management related to the Jenkins CI configuration. + +Project Scope +------------- + +#. Automated regression testing of VPP code changes + - Functionality of VPP data plane, network control plane, management plane against functional specifications. + - Performance of VPP data plane including non-drop-rate packet throughput and delay, against established reference benchmarks. + - Performance of network control plane against established reference benchmarks. + - Performance of management plane against established reference benchmarks. +#. Test case definitions driven by supported and planned VPP functionality, interfaces and performance: + - Uni-dimensional tests: Data plane, (Network) Control plane, Management plane. + - Multi-dimensional tests: Use case driven. +#. Integration with FD.io Continuous Integration system including FD.io Gerrit and Jenkins + - Automated test execution triggered by VPP-VERIFY jobs other VPP and CSIT project jobs. +#. Integration with LF VPP test execution environment + - Functional tests execution on LF hosted VM environment. + - Performance and functional tests execution on LF hosted physical compute environment. + - Subset of tests executed on LF hosted physical compute running VIRL (Virtual Internet Routing Lab). + +|csit| Documentation +-------------------- + +Python Library +############## + +.. toctree:: + :maxdepth: 2 + :glob: + + resources.libraries.python + +Robot Library +############# + +.. toctree:: + :maxdepth: 2 + :glob: + + resources.libraries.robot + +Functional Tests +################ + +.. toctree:: + :maxdepth: 3 + :glob: + + tests.func + +Performance Tests +################# + +.. toctree:: + :maxdepth: 2 + :glob: + + tests.perf + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/resources/tools/doc_gen/src/requirements.txt b/resources/tools/doc_gen/src/requirements.txt new file mode 100644 index 0000000000..8f3e9a5503 --- /dev/null +++ b/resources/tools/doc_gen/src/requirements.txt @@ -0,0 +1,3 @@ +Sphinx==1.4.8 +sphinxcontrib_robotdoc==0.8.0 +sphinx-rtd-theme
\ No newline at end of file diff --git a/resources/tools/doc_gen/src/resources.libraries.python.rst b/resources/tools/doc_gen/src/resources.libraries.python.rst new file mode 100644 index 0000000000..a5ee9dd0c0 --- /dev/null +++ b/resources/tools/doc_gen/src/resources.libraries.python.rst @@ -0,0 +1,3 @@ +Python Library +============== + diff --git a/resources/tools/doc_gen/src/resources.libraries.robot.rst b/resources/tools/doc_gen/src/resources.libraries.robot.rst new file mode 100644 index 0000000000..9d93f6c42c --- /dev/null +++ b/resources/tools/doc_gen/src/resources.libraries.robot.rst @@ -0,0 +1,3 @@ +Robot Library +============= + diff --git a/resources/tools/doc_gen/src/tests.func.rst b/resources/tools/doc_gen/src/tests.func.rst new file mode 100644 index 0000000000..74b26f175e --- /dev/null +++ b/resources/tools/doc_gen/src/tests.func.rst @@ -0,0 +1,3 @@ +Functional Tests +================ + diff --git a/resources/tools/doc_gen/src/tests.perf.rst b/resources/tools/doc_gen/src/tests.perf.rst new file mode 100644 index 0000000000..226545ba84 --- /dev/null +++ b/resources/tools/doc_gen/src/tests.perf.rst @@ -0,0 +1,3 @@ +Performance Tests +================= + |
