diff --git a/doc/source/conf.py b/doc/source/conf.py index 0e88dcd..b5f1f2a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.graphviz', 'openstackdocstheme', 'sphinxcontrib.rsvgconverter', ] @@ -36,6 +37,12 @@ source_suffix = '.rst' # The master toctree document. master_doc = 'index' +# openstackdocstheme options +openstackdocs_repo_name = 'openstack/venus' +openstackdocs_bug_project = 'venus' +openstackdocs_bug_tag = 'doc' +openstackdocs_pdf_link = True + config_generator_config_file = '../../tools/config/venus-config-generator.conf' sample_config_basename = '_static/venus' @@ -53,3 +60,45 @@ add_module_names = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'native' + +# -- Options for HTML output -------------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'venusdoc' + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = 'Venus' +html_theme = 'openstackdocs' + +# -- 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. + # openany: Skip blank pages in generated PDFs + 'maxlistdepth': 10, + 'extraclassoptions': 'openany,oneside', + 'preamble': r'\setcounter{tocdepth}{2}', + 'makeindex': '', + 'printindex': '', +} + +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +# Some distros are missing xindy +latex_use_xindy = False + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + 'doc-venus.tex', + 'Venus Documentation', + 'OpenStack Foundation', 'manual'), +] diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000..ec74981 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,73 @@ +============================ +So You Want to Contribute... +============================ + +For general information on contributing to OpenStack, please check out the +`contributor guide `_ to get started. +It covers all the basics that are common to all OpenStack projects: the +accounts you need, the basics of interacting with our Gerrit review system, +how we communicate as a community, etc. + +Below will cover the more project specific information you need to get started +with {{cookiecutter.service}}. + +Communication +~~~~~~~~~~~~~ + +We use the #openstack-venus IRC channel. + +The weekly meetings happen in this channel. You can find the meeting times, +previous meeting logs and proposed meeting agendas at +`Cyborg Team Meeting Page +`_. + +Contacting the Core Team +~~~~~~~~~~~~~~~~~~~~~~~~ + +The core reviewers of Cyborg and their emails are listed in +`Cyborg core team `_. + +New Feature Planning +~~~~~~~~~~~~~~~~~~~~ + +To propose or plan new features, we add a new story in the +`Cyborg Launchpad +`_ +and/or propose a specification in the +`venus-specs `_ repository. + +Task Tracking +~~~~~~~~~~~~~ + +We track our tasks in the `Launchpad `_. + +If you're looking for some smaller, easier work item to pick up and get started +on, ask in the IRC meeting. + +Reporting a Bug +~~~~~~~~~~~~~~~ + +You found an issue and want to make sure we are aware of it? You can do so on +`Launchpad `__. +More info about Launchpad usage can be found on `OpenStack docs page +`_. + +Getting Your Patch Merged +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To merge a patch, it must pass all voting Zuul checks and get two +2s from +core reviewers. We strive to avoid scenarios where one person from a company +or organization proposes a patch, and two other core reviewers from the +same organization approve it to get it merged. In other words, at least +one among the patch author and the two approving reviwers must be from +another organization. + +We are constantly striving to improve quality. Proposed patches must +generally have unit tests and/or functional tests that cover the changes, +and strive to improve code coverage. + +Project Team Lead Duties +~~~~~~~~~~~~~~~~~~~~~~~~ + +All common PTL duties are enumerated in the `PTL guide +`_. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..db89ee5 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,30 @@ +=========================== + Contributor Documentation +=========================== + +Contributing to Cybrog gives you the power to help add features, fix bugs, +enhance documentation, and increase testing. Contributions of any type are +valuable, and part of what keeps the project going. Here are a list of +resources to get your started. + +Basic Information +================= + +.. toctree:: + :maxdepth: 2 + + contributing + + +Reviewing +========= + +* :doc:`/contributor/releasenotes`: When we need a release note for a + contribution. + +.. # NOTE: toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + releasenotes diff --git a/doc/source/contributor/releasenotes.rst b/doc/source/contributor/releasenotes.rst new file mode 100644 index 0000000..92e5f12 --- /dev/null +++ b/doc/source/contributor/releasenotes.rst @@ -0,0 +1,63 @@ +.. _releasenotes: + +Release Notes +============= + +What is reno ? +-------------- + +Venus uses `reno `__ for providing +release notes in-tree. That means that a patch can include a *reno file* or a +series can have a follow-on change containing that file explaining what the +impact is. + +A *reno file* is a YAML file written in the ``releasenotes/notes`` tree which +is generated using the *reno* tool this way: + +.. code-block:: bash + + $ tox -e venv -- reno new + +where usually ```` can be ``bp-`` for a +blueprint or ``bug-XXXXXX`` for a bugfix. + +Refer to the `reno documentation +`__ for more +information. + + +When a release note is needed +----------------------------- + +A release note is required anytime a reno section is needed. Below are some +examples for each section. Any sections that would be blank should be left out +of the note file entirely. If no section is needed, then you know you don't +need to provide a release note :-) + +* ``upgrade`` + * The patch has an `UpgradeImpact `_ tag + * A DB change needs some deployer modification (like a migration) + * A configuration option change (deprecation, removal or modified default) + * some specific changes that have a `DocImpact `_ tag + but require further action from an deployer perspective + * any patch that requires an action from the deployer in general + +* ``security`` + * If the patch fixes a known vulnerability + +* ``features`` + * If the patch has an `APIImpact `_ tag + * For Venus api and python-venusclient changes, if it adds or changes a + new command, including adding new options to existing commands + +* ``critical`` + * Bugfixes categorized as Critical in launchpad *impacting users* + +* ``fixes`` + * No clear definition of such bugfixes. Hairy long-standing bugs with high + importance that have been fixed are good candidates though. + +Three sections are left intentionally unexplained (``prelude``, ``issues`` and +``other``). Those are targeted to be filled in close to the release time for +providing details about the soon-ish release. Don't use them unless you know +exactly what you are doing. diff --git a/doc/source/index.rst b/doc/source/index.rst index 8196b93..40f8ad9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,3 +16,12 @@ Overview .. toctree:: :maxdepth: 1 + + +Documentation for Developers +---------------------------- + +.. toctree:: + :maxdepth: 1 + + contributor/index diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index d490ee2..26f5295 100644 --- a/releasenotes/source/conf.py +++ b/releasenotes/source/conf.py @@ -1,4 +1,27 @@ -# -*- coding: utf-8 -*- +# 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. + +# Cyborg Release Notes documentation build configuration file, created by +# sphinx-quickstart on Thu April 1 16:50:32 2020. +# +# 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. # -- General configuration ------------------------------------------------ @@ -16,7 +39,9 @@ extensions = [ # openstackdocstheme options openstackdocs_repo_name = 'openstack/venus' -openstackdocs_use_storyboard = True +openstackdocs_bug_project = 'venus' +openstackdocs_bug_tag = 'doc' +openstackdocs_pdf_link = True # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: