diff --git a/.gitignore b/.gitignore index 62f262d..a475034 100644 --- a/.gitignore +++ b/.gitignore @@ -63,7 +63,8 @@ instance/ .scrapy # Sphinx documentation -docs/_build/ +docs/build/ +docs/source/usage/help_output.inc # PyBuilder target/ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 26914d8..6998a22 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -126,4 +126,14 @@ Tips To run a subset of tests:: -$ py.test tests.test_disruption_generator + $ py.test tests.test_disruption_generator + +To build documentation locally:: + + $ make docs + +You can also let the docs be built dynamically while working on them. +You can see sphinx output in console and you can see your changes straight away in browser (that is after you hit +refresh button). You can achieve this by:: + + $ make servedocs diff --git a/Makefile b/Makefile index 7073559..e71ada9 100644 --- a/Makefile +++ b/Makefile @@ -65,15 +65,12 @@ coverage: ## check code coverage quickly with the default Python coverage html $(BROWSER) htmlcov/index.html -docs: ## generate Sphinx HTML documentation, including API docs - rm -f docs/disruption_generator.rst - rm -f docs/modules.rst - sphinx-apidoc -o docs/ disruption_generator +docs: ## generate Sphinx HTML documentation $(MAKE) -C docs clean $(MAKE) -C docs html - $(BROWSER) docs/_build/html/index.html + $(BROWSER) docs/build/html/index.html -servedocs: docs ## compile the docs watching for changes +servedocs: docs ## Build docs dynamically while making changes on them watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D . docker: ## generate docker container @@ -89,7 +86,7 @@ dist: clean ## builds source and wheel package install: clean ## install the package to the active Python's site-packages pip install pipenv - PIPENV_IGNORE_VIRTUALENVS=1 pipenv install --dev + PIPENV_IGNORE_VIRTUALENVS=1 pipenv install --dev --skip-lock pipenv run python setup.py install init: diff --git a/disruption_generator/cli.py b/disruption_generator/cli.py index 71ec6dc..a046acb 100644 --- a/disruption_generator/cli.py +++ b/disruption_generator/cli.py @@ -48,6 +48,12 @@ def main(experiments_path, ssh_host_key): async def execute(experiments_path, ssh_host_key): + """Find, parse and execute experiments. + + :param experiments_path: Path to directory with definitions of experiments. + :return: 0 on success, else 1. + :rtype: int + """ ssh_host_key = ssh_host_key or [ssh_host_key] _files = [] for (dirpath, dirnames, filenames) in walk(experiments_path): diff --git a/docs/Makefile b/docs/Makefile index 688aa68..cace317 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,11 +2,11 @@ # # You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = python -msphinx +SPHINXOPTS = -v +SPHINXBUILD = sphinx-build SPHINXPROJ = disruption_generator -SOURCEDIR = . -BUILDDIR = _build +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/authors.rst b/docs/authors.rst deleted file mode 100644 index e122f91..0000000 --- a/docs/authors.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../AUTHORS.rst diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index e582053..0000000 --- a/docs/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CONTRIBUTING.rst diff --git a/docs/history.rst b/docs/history.rst deleted file mode 100644 index 2506499..0000000 --- a/docs/history.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../HISTORY.rst diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 01bbb7a..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=python -msphinx -) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=disruption_generator - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The Sphinx module was not found. Make sure you have Sphinx installed, - echo.then set the SPHINXBUILD environment variable to point to the full - echo.path of the 'sphinx-build' executable. Alternatively you may add the - echo.Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index 72a3355..0000000 --- a/docs/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/docs/source/authors.rst b/docs/source/authors.rst new file mode 100644 index 0000000..7739272 --- /dev/null +++ b/docs/source/authors.rst @@ -0,0 +1 @@ +.. include:: ../../AUTHORS.rst diff --git a/docs/conf.py b/docs/source/conf.py old mode 100755 new mode 100644 similarity index 66% rename from docs/conf.py rename to docs/source/conf.py index 9969ba5..7c44beb --- a/docs/conf.py +++ b/docs/source/conf.py @@ -1,38 +1,45 @@ -#!/usr/bin/env python # -*- coding: utf-8 -*- # -# disruption_generator documentation build configuration file, created by -# sphinx-quickstart on Fri Jun 9 13:47:02 2017. +# Configuration file for the Sphinx documentation builder. # -# 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. +# 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/stable/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. +# 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("..")) +sys.path.insert(0, os.path.abspath("../..")) import disruption_generator -# -- General configuration --------------------------------------------- +# -- Project information ----------------------------------------------------- + +project = "Disruption Generator" +copyright = "2018, Gonzalo Rafuls" +author = "Gonzalo Rafuls" + +# The short X.Y version +version = disruption_generator.__version__ +# The full version, including alpha/beta/rc tags +release = disruption_generator.__version__ + + +# -- 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 coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode"] # Add any paths that contain templates here, relative to this directory. @@ -47,20 +54,6 @@ # The master toctree document. master_doc = "index" -# General information about the project. -project = u"Disruption Generator" -copyright = u"2018, Gonzalo Rafuls" -author = u"Gonzalo Rafuls" - -# 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 = disruption_generator.__version__ -# The full version, including alpha/beta/rc tags. -release = disruption_generator.__version__ - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -70,25 +63,22 @@ # 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"] +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ["../build"] # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - -# -- Options for HTML output ------------------------------------------- +# -- 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" -# 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 +# 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 = {} @@ -98,14 +88,24 @@ # 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 --------------------------------------- +# -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = "disruption_generatordoc" -# -- Options for LaTeX output ------------------------------------------ +# -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). @@ -123,20 +123,20 @@ } # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto, manual, or own class]). +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, "disruption_generator.tex", - u"Disruption Generator Documentation", - u"Gonzalo Rafuls", + "Disruption Generator Documentation", + "Gonzalo Rafuls", "manual", - ) + ) ] -# -- Options for manual page output ------------------------------------ +# -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). @@ -144,14 +144,14 @@ ( master_doc, "disruption_generator", - u"Disruption Generator Documentation", + "Disruption Generator Documentation", [author], 1, ) ] -# -- Options for Texinfo output ---------------------------------------- +# -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, @@ -160,10 +160,13 @@ ( master_doc, "disruption_generator", - u"Disruption Generator Documentation", + "Disruption Generator Documentation", author, "disruption_generator", "One line description of project.", "Miscellaneous", ) ] + + +# -- Extension configuration ------------------------------------------------- diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 0000000..ac7b6bc --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1 @@ +.. include:: ../../CONTRIBUTING.rst diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..68796f3 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,19 @@ +.. highlight:: shell + +========================== +Frequently Asked Questions +========================== + +**Question:** How can I simulate "dummy" log filling if I just want to try something out? + +**Answer:** You can use our development utility fake_logger. More info on its usage can be found in +`disruption_generator/utils/fake_logger.py`. You can run it for example like this:: + + python fake_logger.py --log-file dummy.log --append --max-interval 2 --randomize --target-msg "FINISH" --seconds 0 + +------------ + +**Question:** How can I configure logging levels of `disruption_generator`? + +**Answer:** Generally speaking by creating a file called `custom_logging.yaml` in `disruption_generator` directory and +overriding default values in it. More info on this process can be found in `disruption_generator/default_logging.yaml`. diff --git a/docs/source/history.rst b/docs/source/history.rst new file mode 100644 index 0000000..5f2e348 --- /dev/null +++ b/docs/source/history.rst @@ -0,0 +1 @@ +.. include:: ../../HISTORY.rst diff --git a/docs/index.rst b/docs/source/index.rst similarity index 65% rename from docs/index.rst rename to docs/source/index.rst index de5a093..c9a8e58 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -5,16 +5,10 @@ Welcome to Disruption Generator's documentation! :maxdepth: 2 :caption: Contents: - readme + Introduction installation usage - modules contributing + faq authors history - -Indices and tables -================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/installation.rst b/docs/source/installation.rst similarity index 100% rename from docs/installation.rst rename to docs/source/installation.rst diff --git a/docs/source/readme.rst b/docs/source/readme.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/docs/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..e6b2fc2 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,19 @@ +===== +Usage +===== + +Copy public key to the target host:: + ssh-copy-id -i root@ + +To use Disruption Generator:: + + Usage: disruption_generator [OPTIONS] + Console script for disruption_generator. + + Options: + -e, --experiments-path DIRECTORY + Path to experiments yamls + --version Show the version and exit. + --help Show this message and exit. + + diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index 5e7cd26..0000000 --- a/docs/usage.rst +++ /dev/null @@ -1,22 +0,0 @@ -===== -Usage -===== - -Copy public key to the target host:: - ssh-copy-id -i root@ - -To use Disruption Generator:: - - Usage: disruption_generator [OPTIONS] - Console script for disruption_generator. - - Options: - -e, --experiments-path DIRECTORY - Path to experiments yamls - --version Show the version and exit. - --help Show this message and exit. - - -Custom configuration options can be found in top-level config.py: - -- EXPERIMENTS_DIR can be used to point to a custom experiments directory