From 94c32c0a34b88b50ac6e73901e3090deb96596c2 Mon Sep 17 00:00:00 2001 From: Anton Studenov Date: Mon, 23 May 2016 17:16:11 +0300 Subject: [PATCH] Fix docs build - fixed recursion error in templates.rst - docs/source/modules added to .gitignore - added setup.cfg to put html docs to right place - docs renamed to doc (convention for openstack community) Change-Id: I530228d0a764302ad7ca9d71be98856188c3fdcb --- .gitignore | 4 +- {docs => doc}/Makefile | 0 {docs => doc}/source/clsdiagram.rst | 0 {docs => doc}/source/commandline.rst | 0 {docs => doc}/source/conf.py | 34 ++++----- {docs => doc}/source/getstart.rst | 0 {docs => doc}/source/index.rst | 0 {docs => doc}/source/install.rst | 0 {docs => doc}/source/modules.rst | 0 doc/source/modules/README.txt | 1 + .../baremetal_example.yaml.rst | 4 +- .../default_example.yaml.rst | 3 +- .../tagged_networks_example.yaml.rst | 3 +- {docs => doc}/source/templates.rst | 32 +++++---- docs/source/modules/devops.driver.dummy.rst | 22 ------ docs/source/modules/devops.driver.ipmi.rst | 22 ------ docs/source/modules/devops.driver.libvirt.rst | 30 -------- docs/source/modules/devops.driver.rst | 19 ----- docs/source/modules/devops.helpers.rst | 70 ------------------- docs/source/modules/devops.migrations.rst | 30 -------- docs/source/modules/devops.models.rst | 54 -------------- docs/source/modules/devops.rst | 49 ------------- docs/source/modules/devops.tests.rst | 62 ---------------- docs/source/modules/modules.rst | 7 -- setup.cfg | 4 ++ 25 files changed, 51 insertions(+), 399 deletions(-) rename {docs => doc}/Makefile (100%) rename {docs => doc}/source/clsdiagram.rst (100%) rename {docs => doc}/source/commandline.rst (100%) rename {docs => doc}/source/conf.py (93%) rename {docs => doc}/source/getstart.rst (100%) rename {docs => doc}/source/index.rst (100%) rename {docs => doc}/source/install.rst (100%) rename {docs => doc}/source/modules.rst (100%) create mode 100644 doc/source/modules/README.txt rename {docs/source/templates => doc/source/template_examples}/baremetal_example.yaml.rst (99%) rename {docs/source/templates => doc/source/template_examples}/default_example.yaml.rst (99%) rename {docs/source/templates => doc/source/template_examples}/tagged_networks_example.yaml.rst (99%) rename {docs => doc}/source/templates.rst (94%) delete mode 100644 docs/source/modules/devops.driver.dummy.rst delete mode 100644 docs/source/modules/devops.driver.ipmi.rst delete mode 100644 docs/source/modules/devops.driver.libvirt.rst delete mode 100644 docs/source/modules/devops.driver.rst delete mode 100644 docs/source/modules/devops.helpers.rst delete mode 100644 docs/source/modules/devops.migrations.rst delete mode 100644 docs/source/modules/devops.models.rst delete mode 100644 docs/source/modules/devops.rst delete mode 100644 docs/source/modules/devops.tests.rst delete mode 100644 docs/source/modules/modules.rst create mode 100644 setup.cfg diff --git a/.gitignore b/.gitignore index 0c2e9048..725d3e53 100644 --- a/.gitignore +++ b/.gitignore @@ -48,7 +48,9 @@ coverage.xml *.log # Sphinx documentation -docs/_build/ +doc/build/ +# autogenerated doc sources +doc/source/modules/ # PyBuilder target/ diff --git a/docs/Makefile b/doc/Makefile similarity index 100% rename from docs/Makefile rename to doc/Makefile diff --git a/docs/source/clsdiagram.rst b/doc/source/clsdiagram.rst similarity index 100% rename from docs/source/clsdiagram.rst rename to doc/source/clsdiagram.rst diff --git a/docs/source/commandline.rst b/doc/source/commandline.rst similarity index 100% rename from docs/source/commandline.rst rename to doc/source/commandline.rst diff --git a/docs/source/conf.py b/doc/source/conf.py similarity index 93% rename from docs/source/conf.py rename to doc/source/conf.py index e4f08f34..4e42a44a 100644 --- a/docs/source/conf.py +++ b/doc/source/conf.py @@ -13,24 +13,27 @@ # serve to show the default. import os -import sys - -# 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. -sys.path.insert(0, os.path.abspath('.')) -sys.path.insert(0, os.path.abspath('../')) -sys.path.insert(0, os.path.abspath('../../')) - +import glob from sphinx.apidoc import main as sphinx_apidoc_main -import shutil -shutil.rmtree('modules', ignore_errors=True) + +# remove autogenerated rst files +for f in glob.glob('modules/*.rst'): + os.remove(f) + +# generate docs sphinx_apidoc_main([ '', - '-o', - 'modules', - '../../devops' + # output dir + '-o', 'modules', + # source dir + '../../devops', + # exclude dirs + '../../devops/settings.py', + '../../devops/test_settings.py', + '../../devops/migrations/', + '../../devops/tests/', + '../../devops/templates/', ]) # -- General configuration ---------------------------------------------------- @@ -81,8 +84,7 @@ release = '3.0.0' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = [ - '**test**', - '**migration**', + # NOTE: use sphinx_apidoc_main to exclude source dirs ] # The reST default role (used for this markup: `text`) to use for diff --git a/docs/source/getstart.rst b/doc/source/getstart.rst similarity index 100% rename from docs/source/getstart.rst rename to doc/source/getstart.rst diff --git a/docs/source/index.rst b/doc/source/index.rst similarity index 100% rename from docs/source/index.rst rename to doc/source/index.rst diff --git a/docs/source/install.rst b/doc/source/install.rst similarity index 100% rename from docs/source/install.rst rename to doc/source/install.rst diff --git a/docs/source/modules.rst b/doc/source/modules.rst similarity index 100% rename from docs/source/modules.rst rename to doc/source/modules.rst diff --git a/doc/source/modules/README.txt b/doc/source/modules/README.txt new file mode 100644 index 00000000..ed39b58f --- /dev/null +++ b/doc/source/modules/README.txt @@ -0,0 +1 @@ +This folder contains auto generated files. Please don't change them directly. \ No newline at end of file diff --git a/docs/source/templates/baremetal_example.yaml.rst b/doc/source/template_examples/baremetal_example.yaml.rst similarity index 99% rename from docs/source/templates/baremetal_example.yaml.rst rename to doc/source/template_examples/baremetal_example.yaml.rst index ae1cbf65..a038f9c6 100644 --- a/docs/source/templates/baremetal_example.yaml.rst +++ b/doc/source/template_examples/baremetal_example.yaml.rst @@ -29,7 +29,9 @@ a baremetal lab (requires the [1] merged to fuel-qa). [1] https://review.openstack.org/#/c/292977/ -.. code-block::yaml + +.. code-block:: yaml + --- aliases: diff --git a/docs/source/templates/default_example.yaml.rst b/doc/source/template_examples/default_example.yaml.rst similarity index 99% rename from docs/source/templates/default_example.yaml.rst rename to doc/source/template_examples/default_example.yaml.rst index bdc29005..78906971 100644 --- a/docs/source/templates/default_example.yaml.rst +++ b/doc/source/template_examples/default_example.yaml.rst @@ -24,7 +24,8 @@ by most of fuel-qa system tests: * STORAGE_POOL_NAME: Pool name for images of VMs * DRIVER_USE_HOST_CPU: CPU type used by VMs can be copied from the host -.. code-block::yaml +.. code-block:: yaml + --- aliases: diff --git a/docs/source/templates/tagged_networks_example.yaml.rst b/doc/source/template_examples/tagged_networks_example.yaml.rst similarity index 99% rename from docs/source/templates/tagged_networks_example.yaml.rst rename to doc/source/template_examples/tagged_networks_example.yaml.rst index fb0bd991..f00f8073 100644 --- a/docs/source/templates/tagged_networks_example.yaml.rst +++ b/doc/source/template_examples/tagged_networks_example.yaml.rst @@ -14,7 +14,8 @@ All slave nodes have only two network interfaces: from this bridge, and getting untagged packets on the libvirt networks 'public', 'management', 'storage' and 'private'. -.. code-block::yaml +.. code-block:: yaml + --- aliases: diff --git a/docs/source/templates.rst b/doc/source/templates.rst similarity index 94% rename from docs/source/templates.rst rename to doc/source/templates.rst index a0d19d28..78452b4a 100644 --- a/docs/source/templates.rst +++ b/doc/source/templates.rst @@ -1,15 +1,18 @@ .. _templates: +Templates +========= + YAML fuel-devops templates are used for creating virtual environments -which describe +which describe + Structure of the YAML template for environment creation ======================================================= - YAML template for fuel-devops contains the following objects: -.. code-block::yaml +.. code-block:: yaml # In the 'template' can be stored all data related to the environment. # There are stored such keys like 'devops_settings' (for fuel-devops) @@ -59,9 +62,10 @@ YAML template for fuel-devops contains the following objects: See detailed examples here: .. toctree:: - :maxdepth: 2 + :glob: + :maxdepth: 1 - templates + template_examples/* =============================== @@ -84,13 +88,13 @@ Example 1: I want to specify the name of a node from the environment variable: -.. code-block::bash +.. code-block:: bash export MY_SLAVE09_NAME=contrail_slave_node-1 , and in the template, for node #9: -.. code-block::yaml +.. code-block:: yaml - name: !os_env MY_SLAVE09_NAME role: fuel_slave @@ -101,13 +105,13 @@ Example 2: I want to override some names of keys in a dictionary, specifying, for example, the name of the bond interface from environment variable: -.. code-block::bash +.. code-block:: bash export MY_FIRST_BOND_IFACE=bond99 , and in the template, for necessary nodes: -.. code-block::yaml +.. code-block:: yaml network_config: !os_env MY_FIRST_BOND_IFACE : @@ -122,7 +126,7 @@ Example 3: I want to specify the whole list of slave interfaces from environment variable: -.. code-block::bash +.. code-block:: bash export MY_SLAVE_INTERFACES="\ [\ @@ -135,7 +139,7 @@ variable: , and in the template for required nodes: -.. code-block::yaml +.. code-block:: yaml - name: slave-05 role: fuel-slave @@ -149,19 +153,19 @@ Example 4: You can !include some parts of the yaml file from other yamls like interfaces_schema1.yaml, interfaces_schema2.yaml or interfaces_schema3.yaml: -.. code-block::yaml +.. code-block:: yaml interfaces: !include interfaces_schema2.yaml , or specifying it with an environment variable: -.. code-block::bash +.. code-block:: bash export LOAD_MY_INTERFACES='!include ./interfaces_schema2.yaml' , and use this variable in the template: -.. code-block::yaml +.. code-block:: yaml interfaces: !os_env LOAD_MY_INTERFACES diff --git a/docs/source/modules/devops.driver.dummy.rst b/docs/source/modules/devops.driver.dummy.rst deleted file mode 100644 index 9a7485e5..00000000 --- a/docs/source/modules/devops.driver.dummy.rst +++ /dev/null @@ -1,22 +0,0 @@ -devops.driver.dummy package -=========================== - -Submodules ----------- - -devops.driver.dummy.dummy_driver module ---------------------------------------- - -.. automodule:: devops.driver.dummy.dummy_driver - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops.driver.dummy - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.driver.ipmi.rst b/docs/source/modules/devops.driver.ipmi.rst deleted file mode 100644 index ac91fd22..00000000 --- a/docs/source/modules/devops.driver.ipmi.rst +++ /dev/null @@ -1,22 +0,0 @@ -devops.driver.ipmi package -========================== - -Submodules ----------- - -devops.driver.ipmi.ipmi_driver module -------------------------------------- - -.. automodule:: devops.driver.ipmi.ipmi_driver - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops.driver.ipmi - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.driver.libvirt.rst b/docs/source/modules/devops.driver.libvirt.rst deleted file mode 100644 index 6d944799..00000000 --- a/docs/source/modules/devops.driver.libvirt.rst +++ /dev/null @@ -1,30 +0,0 @@ -devops.driver.libvirt package -============================= - -Submodules ----------- - -devops.driver.libvirt.libvirt_driver module -------------------------------------------- - -.. automodule:: devops.driver.libvirt.libvirt_driver - :members: - :undoc-members: - :show-inheritance: - -devops.driver.libvirt.libvirt_xml_builder module ------------------------------------------------- - -.. automodule:: devops.driver.libvirt.libvirt_xml_builder - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops.driver.libvirt - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.driver.rst b/docs/source/modules/devops.driver.rst deleted file mode 100644 index ff30913a..00000000 --- a/docs/source/modules/devops.driver.rst +++ /dev/null @@ -1,19 +0,0 @@ -devops.driver package -===================== - -Subpackages ------------ - -.. toctree:: - - devops.driver.dummy - devops.driver.ipmi - devops.driver.libvirt - -Module contents ---------------- - -.. automodule:: devops.driver - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.helpers.rst b/docs/source/modules/devops.helpers.rst deleted file mode 100644 index 9774e557..00000000 --- a/docs/source/modules/devops.helpers.rst +++ /dev/null @@ -1,70 +0,0 @@ -devops.helpers package -====================== - -Submodules ----------- - -devops.helpers.helpers module ------------------------------ - -.. automodule:: devops.helpers.helpers - :members: - :undoc-members: - :show-inheritance: - -devops.helpers.network module ------------------------------ - -.. automodule:: devops.helpers.network - :members: - :undoc-members: - :show-inheritance: - -devops.helpers.node_manager module ----------------------------------- - -.. automodule:: devops.helpers.node_manager - :members: - :undoc-members: - :show-inheritance: - -devops.helpers.ntp module -------------------------- - -.. automodule:: devops.helpers.ntp - :members: - :undoc-members: - :show-inheritance: - -devops.helpers.retry module ---------------------------- - -.. automodule:: devops.helpers.retry - :members: - :undoc-members: - :show-inheritance: - -devops.helpers.scancodes module -------------------------------- - -.. automodule:: devops.helpers.scancodes - :members: - :undoc-members: - :show-inheritance: - -devops.helpers.templates module -------------------------------- - -.. automodule:: devops.helpers.templates - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops.helpers - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.migrations.rst b/docs/source/modules/devops.migrations.rst deleted file mode 100644 index 64f53a16..00000000 --- a/docs/source/modules/devops.migrations.rst +++ /dev/null @@ -1,30 +0,0 @@ -devops.migrations package -========================= - -Submodules ----------- - -devops.migrations.0001_initial module -------------------------------------- - -.. automodule:: devops.migrations.0001_initial - :members: - :undoc-members: - :show-inheritance: - -devops.migrations.0002_add_field_created module ------------------------------------------------ - -.. automodule:: devops.migrations.0002_add_field_created - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops.migrations - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.models.rst b/docs/source/modules/devops.models.rst deleted file mode 100644 index 7acfc58d..00000000 --- a/docs/source/modules/devops.models.rst +++ /dev/null @@ -1,54 +0,0 @@ -devops.models package -===================== - -Submodules ----------- - -devops.models.base module -------------------------- - -.. automodule:: devops.models.base - :members: - :undoc-members: - :show-inheritance: - -devops.models.environment module --------------------------------- - -.. automodule:: devops.models.environment - :members: - :undoc-members: - :show-inheritance: - -devops.models.network module ----------------------------- - -.. automodule:: devops.models.network - :members: - :undoc-members: - :show-inheritance: - -devops.models.node module -------------------------- - -.. automodule:: devops.models.node - :members: - :undoc-members: - :show-inheritance: - -devops.models.volume module ---------------------------- - -.. automodule:: devops.models.volume - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops.models - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.rst b/docs/source/modules/devops.rst deleted file mode 100644 index e7a34c19..00000000 --- a/docs/source/modules/devops.rst +++ /dev/null @@ -1,49 +0,0 @@ -devops package -============== - -Subpackages ------------ - -.. toctree:: - - devops.driver - devops.helpers - devops.migrations - devops.models - devops.tests - -Submodules ----------- - -devops.error module -------------------- - -.. automodule:: devops.error - :members: - :undoc-members: - :show-inheritance: - -devops.settings module ----------------------- - -.. automodule:: devops.settings - :members: - :undoc-members: - :show-inheritance: - -devops.shell module -------------------- - -.. automodule:: devops.shell - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/devops.tests.rst b/docs/source/modules/devops.tests.rst deleted file mode 100644 index 3ddc7099..00000000 --- a/docs/source/modules/devops.tests.rst +++ /dev/null @@ -1,62 +0,0 @@ -devops.tests package -==================== - -Submodules ----------- - -devops.tests.factories module ------------------------------ - -.. automodule:: devops.tests.factories - :members: - :undoc-members: - :show-inheritance: - -devops.tests.test_helpers module --------------------------------- - -.. automodule:: devops.tests.test_helpers - :members: - :undoc-members: - :show-inheritance: - -devops.tests.test_manager module --------------------------------- - -.. automodule:: devops.tests.test_manager - :members: - :undoc-members: - :show-inheritance: - -devops.tests.test_scancodes module ----------------------------------- - -.. automodule:: devops.tests.test_scancodes - :members: - :undoc-members: - :show-inheritance: - -devops.tests.test_shell module ------------------------------- - -.. automodule:: devops.tests.test_shell - :members: - :undoc-members: - :show-inheritance: - -devops.tests.use_cases module ------------------------------ - -.. automodule:: devops.tests.use_cases - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: devops.tests - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/modules/modules.rst b/docs/source/modules/modules.rst deleted file mode 100644 index 2dbd97b6..00000000 --- a/docs/source/modules/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -devops -====== - -.. toctree:: - :maxdepth: 4 - - devops diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 00000000..11d2c442 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,4 @@ +[build_sphinx] +all_files = 1 +build-dir = doc/build +source-dir = doc/source