openstack/freezer
Code Issues Proposed changes

Add Sphinx doc build

Browse Source 
Change-Id: I9742e5261cd666f09a0bd93e2372da6a10f5f69b
Closes-Bug: #1542061
This commit is contained in:
Fausto Marzi 2016-02-04 22:53:26 +00:00
parent 5839011a57
commit ab794d3d36
9 changed files with 304 additions and 261 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -18,6 +18,8 @@ coverage.xml
.testrepository .testrepository
subunit.log subunit.log
.eggs .eggs
AUTHORS
ChangeLog
# Django files that get created during the test runs # Django files that get created during the test runs
.secret_key_store .secret_key_store

27
AUTHORS
View File

@ -1,27 +0,0 @@
Daniel Mellado <danielmelladoarea@gmail.com>
Davide Guerri <davide.guerri@hp.com>
Deklan Dieterly <deklan.dieterly@hpe.com>
Einst Crazy <yu.changcai@99cloud.net>
Erno Kuvaja <jokke@usr.fi>
Fabrizio Fresco <fabrizio.fresco@hp.com>
Fabrizio Vanni <fabrizio.vanni@hp.com>
Fausto Marzi <fausto.marzi@ericsson.com>
Fausto Marzi <fausto.marzi@gmail.com>
Fausto Marzi <fausto.marzi@hp.com>
Fausto Marzi <fausto.marzi@hpe.com>
Federico Ceratto <federico.ceratto@hp.com>
Jeremy Stanley <fungi@yuggoth.org>
Jonas Pfannschmidt <jonas.pfannschmidt@hp.com>
Kenji Yasui <k-yasui@ti.jp.nec.com>
Memo Garcia <sirmemogarcia@gmail.com>
Memo García <sirmemogarcia@gmail.com>
Ondřej Nový <ondrej.novy@firma.seznam.cz>
Pierre-Arthur MATHIEU <pierre-arthur.mathieu@hp.com>
Saad Zaher <eng.szaher@gmail.com>
Vic Howard <victor.r.howard@gmail.com>
Zahari Zahariev <zahari.ven.zahariev@hp.com>
daiki kato <d-kato@wr.jp.nec.com>
eldar nugaev <eldar.nugaev@hp.com>
memo <sirmemogarcia@gmail.com>
sbartel <samuel.bartel@orange.com>
vishal mahajan <vishal.mahajan@nectechnologies.in>

231
ChangeLog
View File

@ -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

3
doc/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
build/
source/ref/
source/api/

265
doc/source/conf.py Normal file
View File

@ -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
# "<project> v<release> 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 <link> 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}

22
doc/source/index.rst Normal file
View File

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

5
setup.cfg
View File

@ -41,6 +41,11 @@ keywords =
setup-hooks = setup-hooks =
pbr.hooks.setup_hook pbr.hooks.setup_hook
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
[files] [files]
packages = packages =
freezer freezer

4
test-requirements.txt
View File

@ -1,11 +1,11 @@
flake8>=2.2.4,<=2.4.1 flake8>=2.2.4,<=2.4.1
pylint==1.4.5 # GNU GPL v2
hacking>=0.10.2,<0.11 hacking>=0.10.2,<0.11
coverage>=3.6 coverage>=3.6
discover discover
mock>=1.2 mock>=1.2
oslosphinx>=2.5.0,!=3.4.0 # Apache-2.0 oslosphinx>=2.5.0,!=3.4.0 # Apache-2.0
pylint==1.4.5 # GNU GPL v2
python-subunit>=0.0.18 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 testrepository>=0.0.18
testtools>=1.4.0 testtools>=1.4.0

6
tox.ini
View File

@ -1,5 +1,5 @@
[tox] [tox]
envlist = py27,pep8,pylint envlist = py27,pep8,pylint,docs
skipsdist = True skipsdist = True
[testenv] [testenv]
@ -40,6 +40,10 @@ norecursedirs = .tox .venv freezer_api freezer/binaries
[testenv:venv] [testenv:venv]
commands = {posargs} commands = {posargs}
[testenv:docs]
commands =
python setup.py build_sphinx
[testenv:cover] [testenv:cover]
commands = python setup.py testr --coverage commands = python setup.py testr --coverage