From 8bac32ebfe9f90eca744baf549ec56b9dd36c91f Mon Sep 17 00:00:00 2001 From: Ildar Musin Date: Tue, 20 Mar 2018 17:42:24 +0300 Subject: [PATCH 1/6] Sphinx configuration --- .gitignore | 2 + docs/Makefile | 20 +++++ docs/source/conf.py | 161 +++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 95 +++++++++++++++++++++++ docs/source/modules.rst | 7 ++ docs/source/testgres.rst | 118 ++++++++++++++++++++++++++++ 6 files changed, 403 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/modules.rst create mode 100644 docs/source/testgres.rst diff --git a/.gitignore b/.gitignore index 4cf6750a..c46fa861 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,8 @@ .eggs/ dist/ build/ +docs/build/ +docs/source/_* env/ venv/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..f33f6be0 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = testgres +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# 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) \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..4e1608cf --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,161 @@ +# -*- 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/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. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) + + +# -- Project information ----------------------------------------------------- + +project = u'testgres' +copyright = u'2016-2018, Postgres Professional' +author = u'Postgres Professional' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'1.5' + + +# -- 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', +#] + +extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon'] + +# 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 = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- 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 +# 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 = 'testgresdoc' + + +# -- 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, 'testgres.tex', u'testgres Documentation', + u'Postgres Professional', '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, 'testgres', u'testgres 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, 'testgres', u'testgres Documentation', + author, 'testgres', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Extension configuration ------------------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..9159e2f3 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,95 @@ + +Testgres documentation +====================== + +Testgres is a PostgreSQL testing utility + +Installation +============ + +To install testgres, run: + +.. code-block:: bash + + pip install testgres + +We encourage you to use ``virtualenv`` for your testing environment. + +Usage +===== + +Environment +----------- + +Note: by default testgres runs ``initdb``, ``pg_ctl``, ``psql`` provided by ``PATH``. + +There are several ways to specify a custom postgres installation: + +- export ``PG_CONFIG`` environment variable pointing to the ``pg_config`` executable; +- export ``PG_BIN`` environment variable pointing to the directory with executable files. + +Example: + +.. code-block:: bash + + export PG_BIN=$HOME/pg_10/bin + python my_tests.py + +Examples +-------- + +Here is an example of what you can do with ``testgres``: + +.. code-block:: python + + # create a node with random name, port, etc + with testgres.get_new_node() as node: + + # run inidb + node.init() + + # start PostgreSQL + node.start() + + # execute a query in a default DB + print(node.execute('select 1')) + + # ... node stops and its files are about to be removed + +Backup & replication +-------------------- + +It's quite easy to create a backup and start a new replica: + +.. code-block:: python + + with testgres.get_new_node('master') as master: + master.init().start() + + # create a backup + with master.backup() as backup: + + # create and start a new replica + replica = backup.spawn_replica('replica').start() + + # catch up with master node + replica.catchup() + + # execute a dummy query + print(replica.execute('postgres', 'select 1')) + +Modules +======= + +.. toctree:: + :maxdepth: 2 + + testgres + + +.. Indices and tables +.. ================== + +.. * :ref:`genindex` +.. * :ref:`modindex` +.. * :ref:`search` diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 00000000..9aeb4d64 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +testgres +======== + +.. toctree:: + :maxdepth: 4 + + testgres diff --git a/docs/source/testgres.rst b/docs/source/testgres.rst new file mode 100644 index 00000000..346f6530 --- /dev/null +++ b/docs/source/testgres.rst @@ -0,0 +1,118 @@ +testgres package +================ + +Submodules +---------- + +testgres.api module +------------------- + +.. automodule:: testgres.api + :members: + :undoc-members: + :show-inheritance: + +testgres.backup module +---------------------- + +.. automodule:: testgres.backup + :members: + :undoc-members: + :show-inheritance: + +testgres.cache module +--------------------- + +.. automodule:: testgres.cache + :members: + :undoc-members: + :show-inheritance: + +testgres.config module +---------------------- + +.. automodule:: testgres.config + :members: + :undoc-members: + :show-inheritance: + +testgres.connection module +-------------------------- + +.. automodule:: testgres.connection + :members: + :undoc-members: + :show-inheritance: + +testgres.consts module +---------------------- + +.. automodule:: testgres.consts + :members: + :undoc-members: + :show-inheritance: + +testgres.decorators module +-------------------------- + +.. automodule:: testgres.decorators + :members: + :undoc-members: + :show-inheritance: + +testgres.defaults module +------------------------ + +.. automodule:: testgres.defaults + :members: + :undoc-members: + :show-inheritance: + +testgres.enums module +--------------------- + +.. automodule:: testgres.enums + :members: + :undoc-members: + :show-inheritance: + +testgres.exceptions module +-------------------------- + +.. automodule:: testgres.exceptions + :members: + :undoc-members: + :show-inheritance: + +testgres.logger module +---------------------- + +.. automodule:: testgres.logger + :members: + :undoc-members: + :show-inheritance: + +testgres.node module +-------------------- + +.. automodule:: testgres.node + :members: + :undoc-members: + :show-inheritance: + +testgres.utils module +--------------------- + +.. automodule:: testgres.utils + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: testgres + :members: + :undoc-members: + :show-inheritance: From aca77bffacde3b3294684cbe6a0f678466a7832a Mon Sep 17 00:00:00 2001 From: Ildar Musin Date: Wed, 21 Mar 2018 14:13:38 +0300 Subject: [PATCH 2/6] Some documentation improvements and refactoring --- docs/README.md | 15 +++++++++++ docs/source/index.rst | 2 +- docs/source/modules.rst | 7 ----- docs/source/testgres.rst | 55 +++++++++++++++++++--------------------- 4 files changed, 42 insertions(+), 37 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/source/modules.rst diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..1e520e83 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +# Building the documentation + +Make sure you have `Sphinx` and `sphinxcontrib-napoleon` packages installed: + +``` +pip install Sphinx sphinxcontrib-napoleon +``` + +Then just run + +``` +make html +``` + +Documentation will be built in `build/html` directory. Other output formats are also available; run `make` without arguments to see the options. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 9159e2f3..566d9a50 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,7 +2,7 @@ Testgres documentation ====================== -Testgres is a PostgreSQL testing utility +Testgres is a PostgreSQL testing framework. Installation ============ diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index 9aeb4d64..00000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -testgres -======== - -.. toctree:: - :maxdepth: 4 - - testgres diff --git a/docs/source/testgres.rst b/docs/source/testgres.rst index 346f6530..63eadc80 100644 --- a/docs/source/testgres.rst +++ b/docs/source/testgres.rst @@ -1,107 +1,104 @@ testgres package ================ -Submodules ----------- - -testgres.api module -------------------- +testgres.api +------------ .. automodule:: testgres.api :members: :undoc-members: :show-inheritance: -testgres.backup module ----------------------- +testgres.backup +--------------- .. automodule:: testgres.backup :members: :undoc-members: :show-inheritance: -testgres.cache module ---------------------- +testgres.cache +-------------- .. automodule:: testgres.cache :members: :undoc-members: :show-inheritance: -testgres.config module ----------------------- +testgres.config +--------------- .. automodule:: testgres.config :members: :undoc-members: :show-inheritance: -testgres.connection module --------------------------- +testgres.connection +------------------- .. automodule:: testgres.connection :members: :undoc-members: :show-inheritance: -testgres.consts module ----------------------- +testgres.consts +--------------- .. automodule:: testgres.consts :members: :undoc-members: :show-inheritance: -testgres.decorators module --------------------------- +testgres.decorators +------------------- .. automodule:: testgres.decorators :members: :undoc-members: :show-inheritance: -testgres.defaults module ------------------------- +testgres.defaults +----------------- .. automodule:: testgres.defaults :members: :undoc-members: :show-inheritance: -testgres.enums module ---------------------- +testgres.enums +-------------- .. automodule:: testgres.enums :members: :undoc-members: :show-inheritance: -testgres.exceptions module --------------------------- +testgres.exceptions +------------------- .. automodule:: testgres.exceptions :members: :undoc-members: :show-inheritance: -testgres.logger module ----------------------- +testgres.logger +--------------- .. automodule:: testgres.logger :members: :undoc-members: :show-inheritance: -testgres.node module --------------------- +testgres.node +------------- .. automodule:: testgres.node :members: :undoc-members: :show-inheritance: -testgres.utils module ---------------------- +testgres.utils +-------------- .. automodule:: testgres.utils :members: From 8c199a40c67deb88a2cf46e245f12fd734e3852b Mon Sep 17 00:00:00 2001 From: Ildar Musin Date: Wed, 21 Mar 2018 14:27:05 +0300 Subject: [PATCH 3/6] Remove redundant comments from Sphinx configuration script --- docs/source/conf.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 4e1608cf..06600d78 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -38,10 +38,6 @@ # 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', -#] - extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon'] # Add any paths that contain templates here, relative to this directory. From 37120a2c7032c47b35a51a3638ad8f00a791a96a Mon Sep 17 00:00:00 2001 From: Ildar Musin Date: Wed, 21 Mar 2018 15:06:49 +0300 Subject: [PATCH 4/6] After yapf been applied --- docs/source/conf.py | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 06600d78..af013ec4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,7 +16,6 @@ import sys sys.path.insert(0, os.path.abspath('../..')) - # -- Project information ----------------------------------------------------- project = u'testgres' @@ -28,7 +27,6 @@ # The full version, including alpha/beta/rc tags release = u'1.5' - # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -67,7 +65,6 @@ # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -96,13 +93,11 @@ # # html_sidebars = {} - # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = 'testgresdoc' - # -- Options for LaTeX output ------------------------------------------------ latex_elements = { @@ -131,16 +126,11 @@ u'Postgres Professional', '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, 'testgres', u'testgres Documentation', - [author], 1) -] - +man_pages = [(master_doc, 'testgres', u'testgres Documentation', [author], 1)] # -- Options for Texinfo output ---------------------------------------------- @@ -148,10 +138,8 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'testgres', u'testgres Documentation', - author, 'testgres', 'One line description of project.', - 'Miscellaneous'), + (master_doc, 'testgres', u'testgres Documentation', author, 'testgres', + 'One line description of project.', 'Miscellaneous'), ] - # -- Extension configuration ------------------------------------------------- From d4f48c87db9418f776cc332ccba514f99af974ab Mon Sep 17 00:00:00 2001 From: Ildar Musin Date: Wed, 21 Mar 2018 15:33:08 +0300 Subject: [PATCH 5/6] Run documentation build along with the tests --- .gitignore | 1 - run_tests.sh | 6 +++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index c46fa861..038d1952 100644 --- a/.gitignore +++ b/.gitignore @@ -5,7 +5,6 @@ dist/ build/ docs/build/ -docs/source/_* env/ venv/ diff --git a/run_tests.sh b/run_tests.sh index 52d5b034..5d986f85 100755 --- a/run_tests.sh +++ b/run_tests.sh @@ -22,7 +22,7 @@ export VIRTUAL_ENV_DISABLE_PROMPT=1 source $VENV_PATH/bin/activate # install utilities -$PIP install coverage flake8 psutil +$PIP install coverage flake8 psutil Sphinx sphinxcontrib-napoleon # install testgres' dependencies export PYTHONPATH=$(pwd) @@ -58,6 +58,10 @@ time \ # show coverage coverage report +# build documentation +cd docs +make html +cd .. # attempt to fix codecov set +eux From 98c96dd7f2a64039fbe5efb7b49f465e0fc0827e Mon Sep 17 00:00:00 2001 From: Ildar Musin Date: Wed, 21 Mar 2018 15:43:43 +0300 Subject: [PATCH 6/6] Remove redundunt _static directory from Sphinx configuration script --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index af013ec4..7ba79351 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -81,7 +81,7 @@ # 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'] +html_static_path = [] # Custom sidebar templates, must be a dictionary that maps document names # to template names.