From ab794d3d36fcd6e8454b91c716ce213fbe0e14e4 Mon Sep 17 00:00:00 2001 From: Fausto Marzi Date: Thu, 4 Feb 2016 22:53:26 +0000 Subject: [PATCH] Add Sphinx doc build Change-Id: I9742e5261cd666f09a0bd93e2372da6a10f5f69b Closes-Bug: #1542061 --- .gitignore | 2 + AUTHORS | 27 ----- ChangeLog | 231 ------------------------------------ doc/.gitignore | 3 + doc/source/conf.py | 265 ++++++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 22 ++++ setup.cfg | 5 + test-requirements.txt | 4 +- tox.ini | 6 +- 9 files changed, 304 insertions(+), 261 deletions(-) delete mode 100644 AUTHORS delete mode 100644 ChangeLog create mode 100644 doc/.gitignore create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/.gitignore b/.gitignore index 4d83324f..b411aa11 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,8 @@ coverage.xml .testrepository subunit.log .eggs +AUTHORS +ChangeLog # Django files that get created during the test runs .secret_key_store diff --git a/AUTHORS b/AUTHORS deleted file mode 100644 index 26ea86a9..00000000 --- a/AUTHORS +++ /dev/null @@ -1,27 +0,0 @@ -Daniel Mellado -Davide Guerri -Deklan Dieterly -Einst Crazy -Erno Kuvaja -Fabrizio Fresco -Fabrizio Vanni -Fausto Marzi -Fausto Marzi -Fausto Marzi -Fausto Marzi -Federico Ceratto -Jeremy Stanley -Jonas Pfannschmidt -Kenji Yasui -Memo Garcia -Memo García -Ondřej Nový -Pierre-Arthur MATHIEU -Saad Zaher -Vic Howard -Zahari Zahariev -daiki kato -eldar nugaev -memo -sbartel -vishal mahajan diff --git a/ChangeLog b/ChangeLog deleted file mode 100644 index 4db36e1c..00000000 --- a/ChangeLog +++ /dev/null @@ -1,231 +0,0 @@ -CHANGES -======= - -* Add check for name=='__main__' -* Adding devstack plugin for freezer gate job -* Command for changing logging level. And pep8 fixing (suddenly this pull request was rejected by jenkins and pep8. so this commit also contains some small style changes for pep8.) -* Fix the parameter order of assertEqual -* Parallel backup -* Fix grammatical and spelling errors in the README.rst file -* Add default namespace to apiclient -* Updated Windows installer and binaries documentation -* use openstack command to create user and project -* Pass proxy enviroment varibles in tox -* Blueprint specs for python-freezerclient repo -* Replace assertEqual(*, None) with assertIsNone in tests -* Drop MANIFEST.in - Because it's already use PBR -* Design specs and considerations for tenant based backups -* Deprecated tox -downloadcache option removed -* Switch freezer-scheduler to oslo.config and oslo.log switch freezer-scheduler to use oslo.config and switch from native python logging module to oslo.log This commit includes: - using oslo.config for parsing cli and config files options - using oslo.log instead of native python logging module - this applied only on freezer-scheduler Implements: blueprint using-oslo-libs -* Removing old integration tests -* Removing obsolete parameters from freezer args (swift related) -* Delete python bytecode before every test run -* Fix typo: my scheduled backup 6 => schedule_backups 6 -* Fixed astroid version to fix pylint -* Initialize freezer-scheduler with insecure mode for keystone v3 -* Freezer Scheduler for Windows -* Import pep3134daemon as local module -* Freezer instructions for Windows -* Fix metadata storage -* Updated python-keystoneclient requirement -* Updated requirements to match Liberty's one -* Fix tests -* Improvements for windows snapshots -* Fix versions for Liberty - -1.1.3 ------ - -* Add backup metadata fields -* Updated LICENSE file and headers -* PBR version needs to be explicitly set on setup.py -* Fix bug on setup.cfg after bin removal -* Fixes for cinder backup -* Removed freezer/bin directory from the repo -* Add cygwin source of cygwin .dll -* Fixed tar command for windows -* Improved freezerc and freezer-agent script management -* Fixed bug on requierments and deps -* Fix nova backup -* Add some FAQ items -* Test coverage improvement -* swift backup should respect chunk size -* Fixed bug on setup.cfg and added author and changelog -* Fixed and improved tox.ini, added subunit as dep -* Update .gitreview for new namespace -* fix integration tests -* Switching to PBR in freezer -* Swift from pytest to testr for unittests -* Forgotten return in ssh -* Test Coverage: Improving test coverage by creation fs_like storage -* Unable to create backup or restore on Mac OS X Resolves bug: 1505629 -* Report error if the choosen algorithm executable is not found -* Test coverage improvments: Validator and Utils -* Freezer should show correct error in case of tar process errors -* Test coverage improvment -* Align requirements.txt to setup.py -* Fix error message if no credentials are provided -* Fix freezer fail when using bandwidth limit -* LVM snapshot mountpoint fix and improved usability -* Fix typo in freezer-agent help -* Fix for race condition for parallel multi-level backup restore -* Throttling bandwidth on Linux for HTTPS -* Fix bug when freezer_main() raise exception -* Fixed deps in setup.py and a bug in tests -* Configurable SSH-PORT -* fix end result of jobs with multiple actions -* First iteration of multiple storages. Unification storages and extraction backup engine -* freezer-scheduler in no-daemon mode -* Default namespace for args options -* Select endpoint type of freezer api service -* UI repo split -* job event requests use specific api endpoint -* Documentation about ssh storage -* Fix for parsing database credentials -* Jobs now start immediately if only interval is provided -* freezer-agent support for keystone v2.0 and v3 -* Updating HP Copyright label -* README info about scheduler and job creation -* Fix for duplicate ID's on backup metadata -* Fix bug with empty client_manager -* remove older then typo -* apiclient support for keystone v2.0 and v3 -* fix loop while getting list of resources from api -* Fix bug on auto lvm snap -* ~/.freezer work_dir created automatically -* basic integration tests for freezer-agent -* fix scheduler job removal when api not available -* Auto snap uses also mount to guess lvm info -* add option to choose compression algorithm with choose between gzip, bzip2 and xz -* Allow freezer-scheduler to find freezerc binary in a non-activated virtualenv -* Possible fix of test_local invocation on jenkins -* Fix for duplicate dependencies -* Fix for issues in the parsing of mysql credentials -* Improve test coverage of storage.py -* Remove freezer_api from freezer repo -* Align pymongo version with global requirements -* Align requirements with global-requirements -* Remove old snapshots for local and ssh -* Auto ssh storage host adding -* add api endpoint /v1/health to support HAProxy -* freezer-scheduler without api service -* Environment inheritance for freezer agent executed by the scheduler -* Improve installation docs for freezer dashboard -* Add freezer dashboard documentation to html files -* fix i18n related to the api -* documentation on integration test procedures -* Change nova and cinder client constructor invocation -* Pluggable storages integration for freezer dashboard -* Backup history -* Flexible way to create, update, delete actions in a job -* Refactoring api interface on freezer_ui -* Backup ID now is not splited by dashes -* Improve README file by removing unexpected git info -* Refactoring logging and translations on freezer_api -* add session properties to json_schemas of job -* SSH Storage In order to give flexibility Freezer needs to be able to store data to a remote file system host using ssh/scp instead instead of Swift -* Refactor api imports to OpenStack Hacking compliant -* Added architecture information to README, updated FAQ -* fix scheduler session_id argument consistency -* update oslo namespace to oslo_config -* Plugable storages architecture and Local storage implementation -* Add Elasticsearch index creation -* Quick fix for freezer dashboard -* Horizon bulk remove for Jobs and Actions -* Job creation for multiple clients -* Horizon implementation for sessions endpoint -* Horizon implementation for jobs api endpoint -* elasticsearch init script -* add execute sync command before execution of backup action -* freezer scheduler -* Honor the env var OS_SERVICE_ENDPOINT so to be able to use adminURL or publicURL Blueprint: endpoint-type -* Fix unwanted output to stdout -* Fix improper segment name when uploading segments to swift -* Add file/dir check upon backup using tar -* Keystone API endpoint discovery -* Add freezer exec action to execute script -* Pluggable storages -* Adding Support for LVM snapshot permission by --lvm-snap-perm Implements: blueprint immutable-snapshot -* Make lvm snap immutable -* correct error message when backup path or file that does not exist -* freezer service API v1 specification reformatted -* Add api support for jobs -* First version of setup.py -* Fix for random test failure on restore.py -* Copied tox.ini and .pylintrc from root directory -* Implementation of Cinder backup compatible mode -* Fix default auth credentials in freezer-api.conf -* Added pylint checks. Fixed import error during python-novaclient import -* Fixed import error on bin/freezerc -* Reduce SQL Server downtime and Snapshot option on windows -* Implementation of nova instance backups -* Ensure in tests that time is check with appropriate timezone offset -* Added config file support in freezerc -* This version contains the following pages: - Overview displays charts/reports (Currently only placeholders) - Configurations allows to define new backup configurations and link them to instances - Backups shows a list of all succesful backups and allows to restore them - Restores shows a history of all restored backups -* Consistent opt args and variable to dentify that same opt arg -* Data consistent way of making cinder backups -* Changed client data description to include "hostname"" -* Added parameters to the "list-backups" python api -* Bandwith limitation functional test -* Incremental LVM functional test -* Fix stale import in freezer_api/storage/driver.py -* Cinder Volumes Backup Implements blueprint: cinder-backup -* freezer api support for action -* Add tests for client registration -* 100% test coverage in freezer/apiclient/backups.py -* Fix initial no_lvm and lvm_level0 tests -* freezer api support for client registration -* Fix broken functional tests freezer_main() -* client retrieval of freezer api endpoint -* Fix bug on --remove-older-then opt -* Fix when freezer runs without arguments -* Refactor environment variable aquisition class -* Fixed references to freezerclient which is now apiclient -* Windows backup and restore incrementals -* Windows support for freezer -* Freezer API -* Implementation of bandwidth-limitation blueprint -* Functional tests and Vagrant environment -* Fix backup sort and related problems -* Fix handling of timestamp in old backup removal -* Remove pyrsync dependency -* Add dry-run execution -* pass optional os_options on to switfclient library -* Fix removal of backup segments -* Main loop refactor -* Proxy implementation -* Fixed bug 1415865 for old backup removal -* Add auth version parameter -* Change in default location of log file -* Add insecure parameter -* Update requirements for environment variables -* Fix for Exception order in freezerc -* Added specs template for freezer -* Updated setup.py to add proper pyrsync installation -* Use Python module MyMySQL instead of MySQLdb -* Add port argument to MySQL connection -* Added unittest for freezer.main -* Exceptions handling revisited and improved -* Added unittest for restore.py -* Add unittest for swift.py and bug fix -* Added unittest for tar.py - -1.1.0 ------ - -* Fixed bug in setup.py and remove test auth file in mysql test -* Added unittest for lvm.py -* Added unittest for utils.py -* Web UI for freezer -* Added unittest for arguments.py -* Unittest for backup.py with coverage >= 90% -* Containers created by Freezer will have freezer_ as prefix -* Fixed a bug in multi level restore and added new --action arg -* Basic structure of the freezer web ui integrated in horizon -* Restore process fails managing big data stream from swift -* Fixed bug launchpad #1382809 to manage token expired -* Added symlink/dereference and modified lvm auto guess options -* Use strings of 8 chars for indexing Swift chunks -* Added --lvm-auto-snap guessing option -* Changed .gitreview .gitignore and added tox.ini -* Freezer initial commit diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..4c2e299e --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,3 @@ +build/ +source/ref/ +source/api/ diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..34394d94 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,265 @@ +# -*- coding: utf-8 -*- +# +# Freezer documentation build configuration file, created by +# sphinx-quickstart on Thu Feb 4 22:27:35 2016. +# +# 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. + +import sys +import os + +# 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('.')) + +# -- 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', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Freezer' +copyright = u'2016, OpenStack' + +# 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 = '2.0' +# The full version, including alpha/beta/rc tags. +release = '2.0.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- 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 = 'default' + +# 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 themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Freezerdoc' + + +# -- 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': '', +} + +# 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 = [ + ('index', 'Freezer.tex', u'Freezer Documentation', + u'OpenStack', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'freezer', u'Freezer Documentation', + [u'OpenStack'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- 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 = [ + ('index', 'Freezer', u'Freezer Documentation', + u'OpenStack', 'Freezer', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..f06fd444 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,22 @@ +.. Freezer documentation master file, created by + sphinx-quickstart on Thu Feb 4 22:27:35 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Freezer's documentation! +=================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/setup.cfg b/setup.cfg index 753c6f5c..e4214c90 100644 --- a/setup.cfg +++ b/setup.cfg @@ -41,6 +41,11 @@ keywords = setup-hooks = pbr.hooks.setup_hook +[build_sphinx] +source-dir = doc/source +build-dir = doc/build +all_files = 1 + [files] packages = freezer diff --git a/test-requirements.txt b/test-requirements.txt index 42692161..82cf7351 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -1,11 +1,11 @@ flake8>=2.2.4,<=2.4.1 -pylint==1.4.5 # GNU GPL v2 hacking>=0.10.2,<0.11 coverage>=3.6 discover mock>=1.2 oslosphinx>=2.5.0,!=3.4.0 # Apache-2.0 +pylint==1.4.5 # GNU GPL v2 python-subunit>=0.0.18 -sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3 +sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3 # BSD testrepository>=0.0.18 testtools>=1.4.0 diff --git a/tox.ini b/tox.ini index 59ea55a8..64ac3836 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = py27,pep8,pylint +envlist = py27,pep8,pylint,docs skipsdist = True [testenv] @@ -40,6 +40,10 @@ norecursedirs = .tox .venv freezer_api freezer/binaries [testenv:venv] commands = {posargs} +[testenv:docs] +commands = + python setup.py build_sphinx + [testenv:cover] commands = python setup.py testr --coverage