Merge pull request #53 from jan-zmeskal/docs

[RFR] Docs restructured

.gitignore

@@ -63,7 +63,8 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
+docs/source/usage/help_output.inc
 
 # PyBuilder
 target/

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

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:

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):

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)

docs/source/authors.rst

@@ -0,0 +1 @@
+.. include:: ../../AUTHORS.rst

docs/conf.py → 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,35 +123,35 @@
 }
 
 # 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).
 man_pages = [
     (
         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 -------------------------------------------------

docs/source/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst

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`.

docs/source/history.rst

@@ -0,0 +1 @@
+.. include:: ../../HISTORY.rst

docs/index.rst → docs/source/index.rst

@@ -5,16 +5,10 @@ Welcome to Disruption Generator's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   readme
+   Introduction <readme>
    installation
    usage
-   modules
    contributing
+   faq
    authors
    history
-
-Indices and tables
-==================
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/source/readme.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst