diff options
| -rw-r--r-- | .gitignore | 7 | ||||
| -rw-r--r-- | CMakeLists.txt | 5 | ||||
| -rwxr-xr-x | clean.sh | 5 | ||||
| -rw-r--r-- | docs/.gitignore | 4 | ||||
| -rw-r--r-- | docs/CMakeLists.txt | 34 | ||||
| -rw-r--r-- | docs/conf.py.in | 173 | ||||
| -rw-r--r-- | docs/docs.rst | 42 | ||||
| -rw-r--r-- | docs/index.rst | 19 | ||||
| -rw-r--r-- | docs/jvpp.rst | 2 | ||||
| -rw-r--r-- | modules/FindSphinx.cmake | 21 |
10 files changed, 307 insertions, 5 deletions
@@ -1,6 +1,7 @@ .idea /build-root/lib /build-root/packages +/build-root/html/ /build-root/.deps.ok /target **/core @@ -12,6 +13,10 @@ _CPack_Packages/ CMakeFiles/ CMakeCache.txt install_manifest.txt -*.cmake +/CPackConfig.cmake +/CPackSourceConfig.cmake *.cbp *.pyc + +/cmake_install.cmake +/CTestTestfile.cmake diff --git a/CMakeLists.txt b/CMakeLists.txt index 38850d5..082a2e7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -16,7 +16,8 @@ cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(jvpp) include(CheckCCompilerFlag) - +# Add custom modules +set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/modules") # # Convert to camel case string from lower case underscored string. # @@ -147,7 +148,7 @@ else() endif() add_subdirectory(java) - +add_subdirectory(docs) # enable Tests include(FindPythonInterp) if(PYTHONINTERP_FOUND) @@ -16,9 +16,12 @@ echo "JVPP cleanup started" make clean rm -rf build-root/packages/* +rm -rf build-root/html/* +rm -rf docs/_build/* +rm -rf docs/_doctrees/* rm -rf java/*.jar # clean cmake cache -find . -iwholename '*cmake*' -not -name CMakeLists.txt -delete +find . -iwholename '*cmake*' -not -name CMakeLists.txt -not -name FindSphinx.cmake -delete # clean cpack cache find . -iwholename '*cpack*' -delete echo "... cleanup finished." diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..62eefe5 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,4 @@ +/_build/* +/_doctrees/* +/Makefile +/cmake_install.cmake diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000..a03333e --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,34 @@ +find_package(Sphinx REQUIRED) + +if(SPHINX_FOUND) + if(NOT DEFINED SPHINX_THEME) + set(SPHINX_THEME default) + endif() + + if(NOT DEFINED SPHINX_THEME_DIR) + set(SPHINX_THEME_DIR) + endif() + + # configured documentation tools and intermediate build results + set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build") + + # Sphinx cache with pickled ReST documents + set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees") + + # HTML output directory + set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/../build-root/html") + + configure_file( + "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in" + "${BINARY_BUILD_DIR}/conf.py" + @ONLY) + + add_custom_target(docs + ${SPHINX_EXECUTABLE} + -q -b html + -c "${BINARY_BUILD_DIR}" + -d "${SPHINX_CACHE_DIR}" + "${CMAKE_CURRENT_SOURCE_DIR}" + "${SPHINX_HTML_DIR}" + COMMENT "Building HTML documentation with Sphinx") +endif() diff --git a/docs/conf.py.in b/docs/conf.py.in new file mode 100644 index 0000000..7eda768 --- /dev/null +++ b/docs/conf.py.in @@ -0,0 +1,173 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# 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('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'JVPP' +copyright = '2019, Cisco' +author = 'Cisco' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '19.04' + + +# -- 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 = [ +] + +# 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 master toctree document. +master_doc = 'index' + +# 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 + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- 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 = '@SPHINX_THEME@' +html_theme_path = ['@SPHINX_THEME_DIR@'] +# 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 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'JVPPdoc' + + +# -- 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, 'JVPP.tex', 'JVPP Documentation', + 'Michal Cmarada', 'manual'), +] + + +# -- 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, 'jvpp', 'JVPP Documentation', + [author], 1) +] + + +# -- 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, 'JVPP', 'JVPP Documentation', + author, 'JVPP', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] diff --git a/docs/docs.rst b/docs/docs.rst new file mode 100644 index 0000000..ea44343 --- /dev/null +++ b/docs/docs.rst @@ -0,0 +1,42 @@ +.. _JVPP DOCUMENTATION: + +.. toctree:: + +Building JVPP documentation +=========================== + +JVPP documentation uses restructured text format as source for generating documentation using sphinx generator. + +Dependencies +------------ + +You need to have sphinx installed in order to build the documentation for JVPP. To do so you can use pip to install it. + +.. code-block:: console + + pip install sphinx + +You can use virtual environment for python or you can install it directly to the system. + + +Building the documentation +-------------------------- + +In order to build the documentation you can use "docs" target which is automatically generated for make if sphinx +generator is available. + +.. code-block:: console + + make docs + +After successful build the generated documentation is available in build-root/html directory. + +Cleanup (Optional) +------------------ + +If you need to clean the build and remove all data that was generated during build (including documentation) you can +use the clean.sh script. + +.. code-block:: console + + ./clean.sh diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..6609e9c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,19 @@ +.. JVPP documentation master file, created by + sphinx-quickstart on Mon Mar 11 12:39:44 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to JVPP's documentation! +================================ + +.. toctree:: + :maxdepth: 2 + + jvpp + docs + + +Indices and tables +================== + +* :ref:`search` diff --git a/docs/jvpp.rst b/docs/jvpp.rst index 15ab0be..513dbb1 100644 --- a/docs/jvpp.rst +++ b/docs/jvpp.rst @@ -27,7 +27,7 @@ https://github.com/FDio/jvpp.git Install dependencies (Optional, one time only) ------------------- +---------------------------------------------- You can install all dependencies using provided install-dep target: diff --git a/modules/FindSphinx.cmake b/modules/FindSphinx.cmake new file mode 100644 index 0000000..cb68e51 --- /dev/null +++ b/modules/FindSphinx.cmake @@ -0,0 +1,21 @@ +find_program(SPHINX_EXECUTABLE NAMES sphinx-build + HINTS + $ENV{SPHINX_DIR} + PATH_SUFFIXES bin + DOC "Sphinx documentation generator" + ) + +include(FindPackageHandleStandardArgs) + +if(NOT SPHINX_EXECUTABLE) + message(STATUS "Sphinx generator not found! Skipping setup for documentation generator.") + set(SPHINX_FOUND false) +else() + find_package_handle_standard_args(Sphinx DEFAULT_MSG + SPHINX_EXECUTABLE + ) + + mark_as_advanced(SPHINX_EXECUTABLE) + set(SPHINX_FOUND true) +endif() + |