openstack
/
docs-specs
Code Issues Proposed changes

Retire docs-specs

Browse Source 
We haven't used this in a long time and with the transition of docs from
a project to a SIG, it's not likely to be used again going forward.

Leave the .zuul.yaml file with noop-jobs to allow this patch to merge.

Change-Id: I557bace8008cc3b4fc1f78264f93291c49f897ad
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Depends-On: Ie3ed990df99057896130ed0f7d5cf6c07db8c962
changes/38/657138/4
Stephen Finucane 4 years ago
parent 81abe0dfe2
commit 5a82d7e9a2
83 changed files with 7 additions and 10330 deletions
Show Stats Download Patch File Download Diff File

18
.gitignore vendored
Unescape View File

@ -1,18 +0,0 @@
.DS_Store
AUTHORS
ChangeLog
build
.tox
.venv
*.egg*
*.swp
*.swo
*.pyc
.testrepository
# Editors
*~
.*.swp
.bak
/.project

9
.zuul.yaml
Unescape View File

@ -1,9 +0,0 @@
- project:
templates:
- openstack-specs-jobs
check:
jobs:
- openstack-tox-py27
gate:
jobs:
- openstack-tox-py27

3
LICENSE
Unescape View File

@ -1,3 +0,0 @@
This work is licensed under a Creative Commons Attribution 3.0 Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode

67
README.rst
Unescape View File

@ -1,62 +1,9 @@
========================
Team and repository tags
========================
This project is no longer maintained.
.. image:: https://governance.openstack.org/tc/badges/docs-specs.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
The contents of this repository are still available in the Git
source code management system. To see the contents of this
repository before it reached its end of life, please check out the
previous commit with "git checkout HEAD^1".
.. Change things from this point on
======================================
OpenStack Documentation Specifications
======================================
This git repository is used to hold approved design specifications for
additions to the OpenStack Documentation program. Reviews of the specs
are done in gerrit, using a similar workflow to how we review and
merge changes to the docs and supporting tools.
The layout of this repository is::
specs/<release>/
You can find an example spec in `doc/source/specs/template.rst`.
Fill it in with the details of a new blueprint for documentation.
For docs, blueprints are required for larger, coordinated projects but
not for small fixes. It's a judgement call for whether you need a
spec, so feel free to ask in the
#openstack-doc IRC channel or on the openstack-docs mailing list.
To propose a specification for a release-specific doc like the install guides
or the configuration reference, add a new file to the
`specs/<release>` directory and post it for review. The implementation
status of a blueprint for a given release can be found by looking at the
blueprint in Launchpad (and the spec links to Launchpad).
Please realize that not all approved blueprints will get fully implemented.
Prior to the Juno development cycle, this repository was not used for spec
reviews. Reviews prior to Juno were completed entirely through `Launchpad
blueprints <http://blueprints.launchpad.net/openstack-manuals>`_.
Please note, Launchpad blueprints are still used for tracking the
current status of blueprints. For more information, see
https://wiki.openstack.org/wiki/Blueprints.
For more information about working with gerrit, see
https://docs.openstack.org/infra/manual/developers.html#development-workflow.
To validate that the specification is syntactically correct (i.e. get more
confidence in the Zuul result), please execute the following command::
$ tox
After running ``tox``, the documentation will be available for viewing in HTML
format in the ``doc/build/`` directory. Please do not check in the generated
HTML files as a part of your commit.
The files are published at https://specs.openstack.org/openstack/docs-specs.
The git repository is located at
https://git.openstack.org/cgit/openstack/docs-specs/.
For any further questions, please email
openstack-discuss@lists.openstack.org.

277
doc/source/conf.py
Unescape View File

@ -1,277 +0,0 @@
# -*- coding: utf-8 -*-
#
# Tempest documentation build configuration file, created by
# sphinx-quickstart on Tue May 21 17:43:32 2013.
#
# 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 datetime
import subprocess
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 = ['openstackdocstheme',
'yasfb',
]
# Allow badges in README
suppress_warnings = ['image.nonlocal_uri']
# Feed configuration for yasfb
feed_base_url = 'http://specs.openstack.org/openstack/docs-specs'
feed_author = 'OpenStack Documentation Team'
todo_include_todos = True
# 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'Docs Specs'
copyright = u'%s, OpenStack Documentation Team' % datetime.date.today().year
# 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 = [
'_build',
'**/template.rst',
'**/skeleton.rst',
]
# 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 = False
# 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 = ['docs-specs.']
# Do not warn about non-local image URI
suppress_warnings = ['image.nonlocal_uri']
# -- 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 = 'openstackdocs'
# 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
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# 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 = False
# If false, no index is generated.
html_use_index = False
# 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 = 'Docs-Specsdoc'
# -- 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]).
latex_documents = [
('index', 'Docs-specs.tex', u'Docs Specs',
u'OpenStack Documentation Team', '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 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', 'Docs-specs', u'Documentation Design Specs',
u'OpenStack Documentation Team', 'docs-specs', 'Design specifications for the Documentation program.',
'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'
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'Docs Specs'
epub_author = u'OpenStack Documentation Team'
epub_publisher = u'OpenStack Documentation Team'
epub_copyright = u'2014, OpenStack Documentation Team'
# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
#epub_exclude_files = []
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True

100
doc/source/index.rst
Unescape View File

@ -1,100 +0,0 @@
.. docs-specs documentation master file
====================================
Documentation Program Specifications
====================================
Rocky approved specs
====================
.. toctree::
:glob:
:maxdepth: 1
specs/rocky/*
Queens approved specs
=====================
.. toctree::
:glob:
:maxdepth: 1
specs/queens/*
Pike approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/pike/*
Ocata approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/ocata/*
Newton approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/newton/*
Mitaka approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/mitaka/*
Liberty approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/liberty/*
Kilo approved specs
===================
.. toctree::
:glob:
:maxdepth: 1
specs/kilo/*
Juno approved specs
===================
.. toctree::
:glob:
:maxdepth: 1
specs/juno/*
Writing specifications
======================
.. toctree::
:maxdepth: 1
README <readme>
==================
Indices and tables
==================
* :ref:`search`

1
doc/source/readme.rst
Unescape View File

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

1
doc/source/specs
Unescape View File

@ -1 +0,0 @@
../../specs

13
requirements.txt
Unescape View File

@ -1,13 +0,0 @@
# The order of packages is significant, because pip processes them in the order
# of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later.
doc8 # Apache-2.0
sphinx>=1.6.2 # BSD
openstackdocstheme>=1.11.0 # Apache-2.0
testrepository>=0.0.18 # Apache-2.0/BSD
testtools>=1.4.0 # MIT
# Note the following is not in global-requirements but this repo is
# not used in repositories in general.
yasfb>=0.6.1

28
setup.cfg
Unescape View File

@ -1,28 +0,0 @@
[metadata]
name = docs-specs
summary = OpenStack Documentation Program Specs
description-file =
README.rst
author = OpenStack
author-email = openstack-discuss@lists.openstack.org
home-page = http://specs.openstack.org/openstack/docs-specs/
classifier =
Intended Audience :: Writers
License :: OSI Approved :: Apache Software License
Operating System :: POSIX :: Linux
Programming Language :: Python
Programming Language :: Python :: 2
Programming Language :: Python :: 2.7
Programming Language :: Python :: 3
Programming Language :: Python :: 3.3
Programming Language :: Python :: 3.5
[build_sphinx]
builders = html
all_files = 1
build-dir = doc/build
source-dir = doc/source
warning-is-error = 1
[wheel]
universal = 1

29
setup.py
Unescape View File

@ -1,29 +0,0 @@
# Copyright (c) 2013 Hewlett-Packard Development Company, L.P.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT
import setuptools
# In python < 2.7.4, a lazy loading of package `pbr` will break
# setuptools if some other modules registered functions in `atexit`.
# solution from: http://bugs.python.org/issue15881#msg170215
try:
import multiprocessing # noqa
except ImportError:
pass
setuptools.setup(
setup_requires=['pbr>=2.0'],
pbr=True)

93
specs/juno/common-glossary-setup.rst
Unescape View File

@ -1,93 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Better share glossary across repositories
==========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/common-glossary-setup
Problem description
===================
The repositories security-doc, operations-guide, and openstack-manuals
share the glossary. In the future the training-guides repository might
use it as well. We should only maintain it in one place.
Also, translation should be only done in one place. Right now,
translations happen in any of these repositories: In openstack-manuals
using a separate POT file, in security-doc and operations-guide as
part of the books.
Currently, the glossary is manually imported in the operations-guide
and security-doc repositories when necessary. The operations-guide
even contains a slightly different header than the version in the
openstack-manuals repository.
The glossary terms must be available to maven at build time to ensure
the links all work correctly.
Proposed change
===============
We should continue to have a master source glossary.
The openstack-manuals repository should continue to be the master
source.
Once a change to the glossary in the master source happens, it will be
proposed to the other repositories via a Jenkins job.
Alternatives
------------
* Using a separate glossary repository and using git submodules in the
other repositories. Our current gerrit setup does not allow git
submodules, so this is not feasible with the current infrastructure.
* Another option would be to checkout the repository containing the
glossary and its translation at a well-known location at build
time. This option requires that every contributor needs to have the
glossary locally when building locally, which is likely too much to
ask of contributors.
* Another alternative may be to create a new openstack/glossary
repository and always copy from there, rather than having
openstack/openstack-manuals/doc/glossary be the storing place.
Raising the level to a repo may help get more contributions to the
glossary.
Implementation
==============
Assignee(s)
-----------
Andreas Jaeger (jaegerandi)
Work Items
----------
* Move files as needed.
* Test solution manually for Security Guide and Operations Guide.
* Change build jobs as needed.
Dependencies
============
Testing
=======
References
==========
Current build of complete glossary:
http://docs.openstack.org/glossary/content/glossary.html

133
specs/juno/create-networking-guide.rst
Unescape View File

@ -1,133 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
================
Networking Guide
================
https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide
Problem description
===================
Since the Havana release, OpenStack has not had a single guide devoted to
understanding and deploying OpenStack Networking. There is some information
in other guides, particularly the Cloud Administrators Guide, but no single
guide that discusses different networking scenarios and solutions.
Proposed change
===============
We should create a Networking Guide, following roughly the outline here:
https://wiki.openstack.org/wiki/NetworkingGuide/TOC
Additionally, a Troubleshooting chapter may be included, subject to
time constraints.
The target audience for this information is cloud administrators who
have experience with OpenStack administration and general system
administration, but who may not be especially knowledgeable about
networking concepts.
This document is targeted for the Juno release. It is explicitly
documenting current best practices for OpenStack Networking (neutron).
It will not document any plug-ins or setups that are deprecated in Juno.
Though the instructions in the guide are for neutron, the introduction
should contain a brief discussion on the different options available,
including nova-network, what this guide focuses on, and why one would
choose those options.
The base architecture uses three nodes: a controller and compute nodes
as set up in the Install Guide, plus a network node to run Neutron
agents. This is the same architecture used in the Cloud Administrators
Guide:
http://docs.openstack.org/admin-guide-cloud/networking_arch.html
It will use the same conventions for naming and services as the Install
Guide, many of which are covered on the wiki:
https://wiki.openstack.org/wiki/Documentation/Guide_conventions
Network types to be covered:
* Local
* VLAN
* GRE
* VXLAN
Mechanisms to be covered:
* Linux Bridge
* OVS
* Open Daylight
* L2 Population
* Proprietary (depending on time constraints)
All instructions will use the ML2 plug-in for mechanism drivers.
Deprecated plug-ins (for example, for OVS or Linux Bridge) will
not be discussed.
Timeline and Events:
* docs swarm (2014-08-09)
* ops meetup (upcoming)
* bug squash day (upcoming)
Alternatives
------------
* Adding more information on networking to guides such as the Cloud
Administrators Guide, Operators Guide, and Install Guide. These
documents already contain some networking information. However,
for them to cover the full breadth of what's proposed could add
significant bulk to each.
Implementation
==============
The Networking Guide will live alongside other guides in the
openstack-manuals repository. There is already some stub content.
Assignee(s)
-----------
Primary assignee:
shaunm-gnome
Other contributors:
nickchase
phil-hopkins-a
ionosphere80
emagana
loquacity
Work Items
----------
* Stub out outline of sections and information to be included.
* Determine whether content already exists, and whether it can be included
or whether it needs to be copied in and edited.
* Have multiple contributors write sections with help from SMEs.
* Review contributions, prioritize content, and possibly prune for release.
Dependencies
============
Need reviewers from Neutron
Testing
=======
* Have SMEs review all conceptual information for accuracy.
* Manually test all instructions to ensure they work.
References
==========
None

125
specs/juno/heat-templates.rst
Unescape View File

@ -1,125 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
======================================
Add documentation about heat templates
======================================
https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates
Problem description
===================
The documentation about how to write heat templates in the openstack-manuals
repository is almost nonexistent. The developer resources are a good starting
point, but don't provide enough information to easily learn how to write
meaningful templates.
The HOT reference (properties and attributes of resources, available functions,
...) is published only for the current development branch, from the heat
documentation (in the developer/ section of the published documentation). This
reference should be available for users along the other references (config
reference, CLI reference), for each released version of heat.
Proposed change
===============
Two changes are proposed:
* Adding a chapter to the user guide
* Providing a new guide: "Heat Orchestration Templates (HOT) Reference Guide"
Adding a chapter to the user guide
----------------------------------
A first section would cover the basic aspects of templates:
* Architecture, format and languages
* Resources definition
* Parameters definition
* Usage of functions and attributes
* Links between resources
This section would cover the base resources: nova server, neutron nets, subnets
and ports, cinder volumes
A second section will document how to use more complex resources such as:
* WaitConditions
* HA and alarming
* AutoScaling
Providing a new guide: the HOT reference
----------------------------------------
This guide will be automatically built from the heat source code and
documentation.
Alternatives
------------
Some alternatives we considered and discuss on the mailing list previously
include:
* Starting a new standalone guide for Templates within openstack-manuals,
sourced in DocBook. We decided the overhead for a new non-automated guide was
too much, and end users are going to want to know this exists.
* Convert the entire End User Guide from DocBook to RST and build with Sphinx,
using the oslosphinx tempate for output. We would lose the translation
toolchain and the PDF from this output chain is not as nice as the DocBook
PDF.
So, to take the best of both tool chains, this proposal chooses to create a
chapter in the End User Guide, ultimately in DocBook, but through an RST path.
Implementation
==============
The documentation will initially be written in RST, to ease developers
contributions. A tool to convert RST to DocBook will be provided.
The template reference provided in the heat repository will be converted to
DocBook and imported in an dedicated guide.
Assignee(s)
-----------
Gauvain Pocentek (gpocentek)
Work Items
----------
* Write the RST to DocBook conversion tool.
* Write the doc in RST.
* Import the result of the conversion in the user guide when ready.
* (Maybe) Automate the import for future updates.
* Automatically publish the reference information for heat templates in a
separate guide.
Dependencies
============
Testing
=======
Minimalistic but functional templates will be provided along the guide. Default
values for parameters will be set to easily work on a devstack environment.
This should ease the testing.
These templates could be provided as part of the `heat-templates repository`_.
.. _`heat-templates repository`: https://git.openstack.org/cgit/openstack/heat-templates
References
==========
* https://git.openstack.org/cgit/openstack/heat/tree/doc/source/template_guide
* https://git.openstack.org/cgit/openstack/heat-templates
* http://docs.openstack.org/developer/heat/template_guide/openstack.html

99
specs/kilo/draft-publishing.rst
Unescape View File

@ -1,99 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================
Publishing of draft manuals
===========================
https://blueprints.launchpad.net/openstack-manuals/+spec/draft-publishing
Problem description
===================
Currently, the following guides are not published at all from the
master branch of the git repository:
* Networking Guide
* Install Guide
* RST User Guides (will change while we discuss this spec)
This makes it difficult for contributors to review current status.
We publish the Configuration reference to
http://docs.openstack.org/trunk/ .
We also have a trunk index page that speaks about "Draft" guides but
references also continuous publishing guides which might confuse users.
Another challenge is drafts of translated guides. Currently we do not
differentiate between fully translated guides and drafts, the only
difference is a link in the index page.
Proposed change
===============
#. Publish draft content to a special location like `/draft/`.
#. Create a single page that references all draft documents and only
those, this page should be hidden. The page is `/draft/draft-index.html`
#. Remove the current `/trunk/index.html` page and links to it.
#. Take care that search machines do not index these pages.
#. Ensure that any partial translated pages do not publish to `/lang/trunk/`
but instead to `/lang/draft`.
For translated content:
#. Publish draft translated content to `/draft/LANG/`.
#. Add the guides to `/draft/draft-index.html` index page.
#. Once guides are reviewed and fully translated , move the content to
`/LANG/` and reference it from a public language specific index page.
Alternatives
------------
#. Keep status quo
#. Publish to another location like `/trunk/`.
Implementation
==============
* Change location of publishing.
* Remove `/trunk/index.html` and links to it.
* Add `/draft/` to :file:`robots.txt`.
* Create new `/draft/draft-index.html` page.
* Review translated documents and publish draft translated documents
to `/draft/LANG/` and add links to `/draft/draft-index.html`.
* Remove old pages.
* Regenerate sitemap.
Assignee(s)
-----------
jaegerandi
Work Items
----------
See implementation.
Dependencies
============
None.
Testing
=======
* Test by going to /trunk and making sure redirect is in place.
* Search for draft content to make sure it's not found.
References
==========
* http://lists.openstack.org/pipermail/openstack-docs/2015-April/006243.html
* https://docs.google.com/spreadsheets/d/10HD6iW1CtfB1qT2wVODYiHdC0ysr4xw392VCqHB-aaY/edit?usp=sharing

151
specs/kilo/installguide-kilo.rst
Unescape View File

@ -1,151 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================================
Installation Guide - Changes for Kilo
=====================================
https://blueprints.launchpad.net/openstack-manuals/+spec/installguide-kilo
Implement mandatory changes and optional enhancements to the Installation
Guide for Kilo.
Problem description
===================
The installation guide requires certain changes to make it work for the
Kilo release of OpenStack.
Proposed change
===============
* Implement mandatory changes and potentially one or more optional
enhancements.
Alternatives
------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Matt Kassawara (ionosphere80)
Other contributors:
Anyone with installation experience
Work Items
----------
* Mandatory changes
* Overall
- As necessary, make changes to successfully install OpenStack on
Ubuntu 14.04, RHEL 7, CentOS 7, Fedora 21, SLES 12, and openSUSE
13.2 using native methods.
- For RabbitMQ, create and use "openstack" account instead of the
guest account.
- As necessary, note that stock configuration files might require
adding configuration stanzas/options rather than editing them.
- As necessary, change any defaults in stock configuration files
that generate deprecation warnings.
- As necessary, replace "tenant" with "project" to align with
Identity v3 API terminology.
- As necessary, replace "message broker" with "message queue" to
improve wording.
* Identity
- Enable version 3 API.
- Replace deprecated eventlet (default web server) with Apache using
`configuration`_ in upstream keystone repository.
.. _`configuration`: https://git.openstack.org/cgit/openstack/keystone/tree/httpd
- Replace SQL token storage driver with Memcached to improve
performance.
- Replace deprecated python-keystoneclient commands with
python-openstackclient commands.
* Image Service
- Enable version 2 API.
* Block Storage
- Replace deprecated v1 API with v2 API.
* Optional changes
* Overall
- Where available, use the /etc/mysql/conf.d directory for additional
database configuration.
- Install upstream RabbitMQ package if distribution includes an old
version.
- Replace python-serviceclient commands with generic
python-openstackclient commands.
* Networking
- Standardize location for Open vSwitch agent configuration.
- Add content for Linux Bridge agent.
* Object Storage
- Add content for standalone (keystone + swift) deployment.
Note: To simplify patches and shrink the review cycle, patches can
address one distribution rather than all distributions. Use separate
patches to address the same content for additional distributions.
Reviewers should take this into account so that one distribution
can complete patches, tests, and publication independent of other
distributions.
Dependencies
============
* Kilo milestone or RC packages for each distribution supported by the
installation guide.
Testing
=======
* All distributions supported by the installation guide must complete
`testing`_ of at least core services (Identity, Image Service, Compute,
and Networking) and successfully launch an instance using both legacy
networking (nova-network) and Networking (neutron). Distributions that
do not meet these criteria risk temporary removal from publication.
.. _`testing`: https://wiki.openstack.org/wiki/KiloDocTesting
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [install-guide]
in the subject, weekly installation guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/InstallGuide
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

237
specs/kilo/migrate-to-new-web-design.rst
Unescape View File

@ -1,237 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================
Migration to New Web Design
===========================
https://blueprints.launchpad.net/openstack-manuals/+spec/redesign-docs-site
The documentation team has reviewed and vetted a new web design. Here are the
example pages:
* `Main page <http://openstack-homepage.bitballoon.com/docs>`_
* `Content view <http://openstack-homepage.bitballoon.com/docs/book>`_
* `Search results <http://openstack-homepage.bitballoon.com/docs/search>`_
* `Example language landing page <http://openstack-homepage.bitballoon.com/docs/ja>`_
This blueprint describes the steps required to implement this new web design.
Problem description
===================
In brief, we have design problems that are addressed with the new design. The
problem to solve is how to get many documents to use the new design.
A related relevant document is the
`Docs.OpenStack.org Redesign Project Brief
<https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit?usp=sharing>`_ which describes the many problems with the current design.
The problem to solve with this blueprint specifically is getting the design
into Sphinx/jinja templates for use with RST source, as well as getting RST
source files from certain DocBook source files.
This is a phased approach to try to get many but not all docs migrated in the
Kilo release time frame.
Proposed change
===============
In the Kilo time frame, migrate these books to the new design:
* End User Guide
* Admin User Guide
As time permits, continue to migrate these books to the new design:
* Cloud Administrator Guide
* High Availability Guide
* API Quick Start Guide
* Virtual Machine Image Guide
To limit the scope of the migration, these books will not be migrated:
* Install Guides
* Operations Guide
* Security Guide
* Architecture Design Guide
These deliverables will remain in DocBook and use the Maven plugin for builds
for the Kilo release.
Alternatives
------------
Rather than use RST/Sphinx for the new design, we could migrate to
markdown/Jekyll which is what the prototype design is already using. The
OpenStack ecosystem currently supports Python systems like Sphinx and
oslosphinx is available with a theme already.
We could get rid of DocBook completely for all books rather than the phased
approach. I don't think that we have the time to do that in a six-month
release, so I'm proposing a phased approach.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
annegentle
Other contributors:
jagerandi
loquacities
klevenstein
dhellman
Work Items
----------
Research:
January 2015
- Investigate how to publish PDF files within this new design.
- Investigate using index.rst collections across repos for new deliverable
assembly. This is not a required task for the migration, but will certainly
help with information architecture going forward towards "every page is page
one" rather than book-like deliverables. (jaegerandi)
Frameworks:
January: Create a taxonomy for suggested tags as part of the `Conventions wiki
page
<https://wiki.openstack.org/wiki/Documentation/Markup_conventions>`_
(klevenstein, loquacities)
DONE January 15, 2015: Create jinja2 templates from Jekyll designs for:
* landing page and search (fifieldt)
DONE February 20, 2015: Create Sphinx template from Jekyll design for:
* content pages (annegentle)
DONE February: Replace static www jinja templates in openstack-manuals with
new design
Proof of concept with content:
February 15, 2015: Migrate DocBook to RST for these books in this priority
order:
* End User Guide
* Admin User Guide
Tracking on wiki page: https://wiki.openstack.org/wiki/Documentation/Migrate
February 28, 2015: Update our build infrastructure
so that Sphinx is used for publishing these documents:
* End User Guide
* Admin User Guide
February 20, 2015: Test templates across browsers to ensure parity with design:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
March 2015: Test translation toolchain. Ying Chun Guo (Daisy) has agreed to
investigate.
DONE February 15, 2015: Update oslosphinx to have new openstackdocs theme:
Currently the theme name is "openstack." Reviewing the plan with Doug Hellman,
we can either keep the openstack theme and start one named "openstackdocs" or
update the openstack theme to be the new design. I prefer to name a new one
"openstackdocs" so that the current openstack theme which can indicate when a
project's doc is incubated remains.
DONE Updated to add: looking at the information architecture of the header,
it looks like it's best to have an openstack docs theme that doesn't
necessarily live in oslosphinx. Oslosphinx is used for
http://specs.openstack.org, http://docs.openstack.org/infra/system-config,
http://governance.openstack.org for example, and
http://docs.openstack.org/infra/system-config has modified the header so that it wouldn't
match the other sites. As a result, the plan is to keep the oslosphinx
theme with oslosphinx and create a theme in a separate repo named
openstackdocsthemes for application to all content published to
http://docs.openstack.org.
March (after proof-of-concept and CI is complete): Migrate DocBook to RST for
these books in this priority order:
* Cloud Administrator Guide
* Virtual Machine Image Guide
* High Availability Guide
* API Quick Start Guide
March: Once migrated, apply new openstackdocstheme template to these repos and
deliverables:
openstack-manuals:
* End User Guide
* Admin User Guide
* Cloud Administrator Guide
* Virtual Machine Image Guide
api-site:
* API Quick Start Guide
ha-guide:
* High Availability Guide
March: Remind projects to update their theme for /developer/ docs for:
* nova
* neutron
* glance
* keystone
* ceilometer
* cinder
* heat
* horizon
* ironic
* sahara
* swift
* trove
Dependencies
============
Foundation web developers hand-off of current design HTML and CSS files.
(Done)
Core olsosphinx reviewers helping with theme creation and reviews. (Done)
Translation team investigate and test translation toolchain.
Testing
=======
We need to test the new HTML design on these browsers/operating systems as a
priority:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
Need to test translation toolchain.
Need to test PDF output if it's possible to get.
References
==========
* https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit?usp=sharing
* https://etherpad.openstack.org/p/docstopicsparissummit
* https://wiki.openstack.org/wiki/Documentation/Markup_conventions
* http://idratherbewriting.com/2012/12/04/what-does-every-page-is-page-one-and-include-it-all-filter-it-afterward-mean/

212
specs/kilo/move-driver-docs.rst
Unescape View File

@ -1,212 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
============================================
Proprietary driver docs in openstack-manuals
============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/move-driver-docs
The Configuration Reference and Cloud Admin Guide include documentation for
various drivers. This spec clarifies the expectations and handling of such
documentation.
The shared goals for driver documentation includes:
- consistent documentation, comparable for each driver.
- version-independent documentation for each driver, meaning the
OpenStack version can change but the driver documentation can remain
the same.
- maintainable documentation for each driver that won't change much
over time and remains accurate.
- reviewable documentation for each driver.
Some benefits we see for this new approach are:
- more flexibility in changing detailed driver documentation on the
appropriate website.
- makes maintenance of detailed driver doc easier for contributing
driver writers since they can choose their source and publishing
chain that fits with their current workflow.
- reduces maintenance for core OpenStack documentation team.
The driver documentation for Compute, Storage, Networking, and
Databases will change as described with the goal of having accurate
documentation. This can be brief version independent information in
the OpenStack manuals with a link to a vendor page with full details
or full version.
Problem description
===================
Many OpenStack projects include drivers to support specific hardware
or software.
Examples are:
* Cinder: block storage drivers
* Neutron: network plug-ins
* Nova: hypervisors
* Trove: Different databases
Many of these drivers are hardware or software specific and can only
be documented by the third-party driver vendor. Some vendors have
great in-tree documentation and update it regularly, others have none
or only outdated documentation. Many vendors have already on
their web page documentation about the drivers, this spec proposes to
move the documentation to the vendor web pages and simply link to
them.
The spec also documents requirements for full documentation as part of
OpenStack manuals.
This will reduce work for both documentation team and vendor drivers
and give clear requirements.
Proposed change
===============
The documentation team will fully document the reference drivers as
specified below and just add short sections for other drivers. If a
vendor wants to document their driver, they are invited - but not
forced - to include their documentation in the Configuration
Reference if they commit to maintain the documentation. However,
other documentation (including the Cloud Admin Guide and Networking
Guide) will not contain content for third-party drivers. In these books,
where third party drivers exist, add the statement: "For other drivers,
see chapter X in the Configuration Reference Guide".
Guidelines for drivers that will be documented fully by the OpenStack
community in the OpenStack documentation:
* The complete solution must be open source and use standard hardware
* The driver must be part of the respective OpenStack repository
* The driver is considered one of the reference drivers
For documentation of other drivers, the following guidelines apply:
* The Configuration Reference will contain a small section for each
driver, see below for details
* Only drivers are covered that are contained in the official
OpenStack project repository for drivers (for example in the main
project repository or the official third-party repository).
If a vendor wants to add more than the minimal documentation, they
need to commit to the following guidelines:
* Assign an editor that is responsible for the content.
* Review and - if necessary - update their driver for each release
cycle.
With this policy, the docs team will document in the Configuration
Reference at least the following drivers:
* For cinder: volume drivers: document LVM and NFS; backup drivers:
document swift
* For glance: Document local storage, cinder, and swift as backends
* For neutron: document ML2 plug-in with the mechanisms drivers
OpenVSwitch and LinuxBridge
* For nova: document KVM (mostly), send Xen open source call for help
* For sahara: apache hadoop
* For trove: document all supported Open Source database engines like
MySQL.
Default section format for external drivers
-------------------------------------------
For each external driver, we want to document briefly the driver in a
way that is version independent and include the current configuration
options.
Each section should follow this format:
* A short paragraph explaining the driver.
* A link with detailed instructions to the vendor site (if there is one)
* A default paragraph like::
Set the following in your cinder.conf, and use the following options
to configure it.
volume_driver = cinder.volume.drivers.smbfs.SmbfsDriver
* And finally the autogenerated configuration options
Driver vendors can send in patches for these or create bugs.
Full documentation by vendors
-----------------------------
If a vendor wants full documentation in the Configuration Reference,
they have to add to the `wiki page
<http://wiki.openstack.org/Documentation/VendorDrivers>`_ a contact
editor that will take care of the vendor driver documentation. The
Documentation team will assign bugs to the contact person, include the
contact person in reviews for the vendor driver, and expects timely
responses.
If vendor driver documentation becomes outdated and the contact person
is not reacting to requests, the Documentation team will change the
full documentation to a minimal version.
The documentation team will review vendor drivers and ensure that the
various driver documents follow a consistent standard.
Alternatives
------------
* Keep status quo: Add all drivers to the Configuration Reference.
* Remove drivers, do not link to them at all - or just link to a
single wiki page.
* Have minimal documentation for all drivers only. This was the
initial idea but rejected since some vendors do not have
documentation on their own.
Implementation
==============
The work will be done in three steps:
#. In the Configuration Reference, bring all driver sections that
are currently just "bare bones" up to the standard mentioned.
#. Work with third-party drivers to convert existing documentation
in the Configuration Reference to the new standard.
#. Purge third-party driver content from other documentation such
as the Cloud Admin Guide.
Assignee(s)
-----------
Entire documentation team
loquacities - informing vendors
Work Items
----------
* Inform third-party driver contacts about change (note that we
have to make this spec known to them earlier to get input on it as
well)
* Ask vendor drivers to assign a contact person and give deadlines.
* Add minimal content for drivers that have no content right now.
* Enhance content (based on suggestion by driver vendors)
* Purge third-party driver content from other documentation.
Dependencies
============
None.
Testing
=======
References
==========
https://etherpad.openstack.org/p/docstopicsparissummit

151
specs/kilo/openstack-firstapp.rst
Unescape View File

@ -1,151 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================================
Writing your First OpenStack Application
========================================
Problem description
===================
Currently, OpenStack is missing documentation similar to other Python
projects, that introduces a new user to the API. One well known "first
app" tutorial in the Python community is the Django web framework's
`tutorial <https://docs.djangoproject.com/en/dev/intro/tutorial01/>`_.
Proposed change
===============
A guide has been written by members of the Application Ecosystem WG
that introduces the OpenStack API, using a non-trivial Python application
that serves as a teaching tool - similar to the poll app in the
equivalent Django tutorial.
Alternatives
------------
None
Implementation
==============
This book has been written for software developers who wish to deploy
applications to OpenStack clouds.
We've assumed that the audience is an experienced programmer, but that
they haven't necessarily created an application for cloud in general, or
for OpenStack in particular.
In addition to learning to deploy applications on OpenStack, the reader
will also learn some best practices for cloud application development.
This tutorial actually involves two applications; the first, a fractal
generator, simply uses mathematical equations to generate images.
However, really, it's just an excuse; the real application is the code that
enables the reader to make use of OpenStack to run it. That application
(and therefore this guide) includes:
* Creating and destroying compute resources.
* Cloud-related architecture decisions, such as microservices and modularity
* Scaling up and down to customize the amount of available resources.
* Object and block storage for persistance of files and databases.
* Orchestration services to automatically adjust to the environment.
* Networking customization for better performance and segregation.
* A few other crazy things we think ordinary folks won't want to do ;).
The guide has been written with a strong preference for the most common
API calls, so it will work across a broad spectrum of OpenStack versions.
In addition, the authors have paid special attention that the first 3 sections
should work almost regardless of OpenStack cloud configuration (basically
Nova, Keystone and Glance are the only requirements, but neutron will be used
if installed).
Repository Location
-------------------
This content should be published to developer.openstack.org.
The content created during the sprint should be separated from the app.
The content created during the sprint documents how to use the OpenStack API
and several OpenStack SDKs and the app is only an example use case. In theory
the used app (Faafo at the moment) can be replaced in the future (or maybe we
want to add a second use case) by an other app.
Additionally, the focus of the documentation placed inside the repository of
the app is different from the focus of the content created during the sprint.
The documentation inside the repository of the app describes how to use
the app itself (how to create a development environment, example outputs, ..),
not how to use OpenStack SDKs and the OpenStack API.
As such, content will live in ``openstack/api-site`` repository like
other documents published to http://developer.openstack.org. Therefore
the review team will be the standard docs reviewers for this
repository.
Multi-SDK support
-----------------
The guide has been written so that support for multiple SDKs is a core part of
its publication. Initial sections have been written for libcloud, and section1
is also available for fog. The design philosophy is that the same prose can be
used, with code samples swapped.
Assignee(s)
-----------
* Sean M. Collins (sean@coreitpro.com)
* Tom Fifield (tom@openstack.org)
* James Dempsey (jamesd@catalyst.net.nz)
* Nick Chase (nchase@mirantis.com)
* Christian Berendt (berendt@b1-systems.de)
Work Items
----------