update documentation
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann
parent
2ab7b64d8b
commit
4d76595e3a
@ -1,5 +0,0 @@
|
||||
====================
|
||||
Administrators guide
|
||||
====================
|
||||
|
||||
Administrators guide of whereto.
|
||||
@ -2,4 +2,5 @@
|
||||
Command line interface reference
|
||||
================================
|
||||
|
||||
CLI reference of whereto.
|
||||
.. autoprogram:: whereto.app:argument_parser
|
||||
:prog: whereto
|
||||
|
||||
@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'openstackdocstheme',
|
||||
'sphinxcontrib.autoprogram',
|
||||
#'sphinx.ext.intersphinx',
|
||||
]
|
||||
|
||||
@ -40,11 +40,6 @@ master_doc = 'index'
|
||||
project = u'whereto'
|
||||
copyright = u'2017, OpenStack Developers'
|
||||
|
||||
# openstackdocstheme options
|
||||
repository_name = 'openstack/whereto'
|
||||
bug_project = 'whereto'
|
||||
bug_tag = ''
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
add_function_parentheses = True
|
||||
|
||||
@ -62,7 +57,7 @@ pygments_style = 'sphinx'
|
||||
# html_theme_path = ["."]
|
||||
# html_theme = '_theme'
|
||||
# html_static_path = ['static']
|
||||
html_theme = 'openstackdocs'
|
||||
html_theme = 'nature'
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = '%sdoc' % project
|
||||
|
||||
@ -1,5 +0,0 @@
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Configuration of whereto.
|
||||
@ -1,4 +0,0 @@
|
||||
============
|
||||
Contributing
|
||||
============
|
||||
.. include:: ../../../CONTRIBUTING.rst
|
||||
@ -2,8 +2,4 @@
|
||||
Contributor Documentation
|
||||
===========================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
contributing
|
||||
|
||||
.. include:: ../../../CONTRIBUTING.rst
|
||||
|
||||
@ -3,24 +3,24 @@
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
=======================================
|
||||
Welcome to the documentation of whereto
|
||||
=======================================
|
||||
========================================
|
||||
whereto: Testing Apache Redirect Rules
|
||||
========================================
|
||||
|
||||
Contents:
|
||||
whereto is an app for testing redirect rules like what may appear in a
|
||||
.htaccess file for Apache. It provides a way to test those rules in CI
|
||||
jobs.
|
||||
|
||||
:Source: http://git.openstack.org/cgit/openstack/whereto
|
||||
:Bugs: http://bugs.launchpad.net/whereto
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
readme
|
||||
install/index
|
||||
library/index
|
||||
contributor/index
|
||||
configuration/index
|
||||
cli/index
|
||||
user/index
|
||||
admin/index
|
||||
reference/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
@ -1,10 +0,0 @@
|
||||
2. Edit the ``/etc/whereto/whereto.conf`` file and complete the following
|
||||
actions:
|
||||
|
||||
* In the ``[database]`` section, configure database access:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[database]
|
||||
...
|
||||
connection = mysql+pymysql://whereto:WHERETO_DBPASS@controller/whereto
|
||||
@ -1,75 +0,0 @@
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before you install and configure the whereto service,
|
||||
you must create a database, service credentials, and API endpoints.
|
||||
|
||||
#. To create the database, complete these steps:
|
||||
|
||||
* Use the database access client to connect to the database
|
||||
server as the ``root`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mysql -u root -p
|
||||
|
||||
* Create the ``whereto`` database:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
CREATE DATABASE whereto;
|
||||
|
||||
* Grant proper access to the ``whereto`` database:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
GRANT ALL PRIVILEGES ON whereto.* TO 'whereto'@'localhost' \
|
||||
IDENTIFIED BY 'WHERETO_DBPASS';
|
||||
GRANT ALL PRIVILEGES ON whereto.* TO 'whereto'@'%' \
|
||||
IDENTIFIED BY 'WHERETO_DBPASS';
|
||||
|
||||
Replace ``WHERETO_DBPASS`` with a suitable password.
|
||||
|
||||
* Exit the database access client.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
exit;
|
||||
|
||||
#. Source the ``admin`` credentials to gain access to
|
||||
admin-only CLI commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ . admin-openrc
|
||||
|
||||
#. To create the service credentials, complete these steps:
|
||||
|
||||
* Create the ``whereto`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack user create --domain default --password-prompt whereto
|
||||
|
||||
* Add the ``admin`` role to the ``whereto`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack role add --project service --user whereto admin
|
||||
|
||||
* Create the whereto service entities:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack service create --name whereto --description "whereto" whereto
|
||||
|
||||
#. Create the whereto service API endpoints:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack endpoint create --region RegionOne \
|
||||
whereto public http://controller:XXXX/vY/%\(tenant_id\)s
|
||||
$ openstack endpoint create --region RegionOne \
|
||||
whereto internal http://controller:XXXX/vY/%\(tenant_id\)s
|
||||
$ openstack endpoint create --region RegionOne \
|
||||
whereto admin http://controller:XXXX/vY/%\(tenant_id\)s
|
||||
@ -1,9 +0,0 @@
|
||||
========================
|
||||
whereto service overview
|
||||
========================
|
||||
The whereto service provides...
|
||||
|
||||
The whereto service consists of the following components:
|
||||
|
||||
``whereto-api`` service
|
||||
Accepts and responds to end user compute API calls...
|
||||
@ -1,17 +1,9 @@
|
||||
==================================
|
||||
whereto service installation guide
|
||||
==================================
|
||||
============================
|
||||
whereto installation guide
|
||||
============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
The whereto package should be installed via ``pip``:
|
||||
|
||||
get_started.rst
|
||||
install.rst
|
||||
verify.rst
|
||||
next-steps.rst
|
||||
.. code-block:: console
|
||||
|
||||
The whereto service (whereto) provides...
|
||||
|
||||
This chapter assumes a working setup of OpenStack following the
|
||||
`OpenStack Installation Tutorial
|
||||
<https://docs.openstack.org/project-install-guide/ocata/>`_.
|
||||
$ pip install whereto
|
||||
|
||||
@ -1,34 +0,0 @@
|
||||
.. _install-obs:
|
||||
|
||||
|
||||
Install and configure for openSUSE and SUSE Linux Enterprise
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section describes how to install and configure the whereto service
|
||||
for openSUSE Leap 42.1 and SUSE Linux Enterprise Server 12 SP1.
|
||||
|
||||
.. include:: common_prerequisites.rst
|
||||
|
||||
Install and configure components
|
||||
--------------------------------
|
||||
|
||||
#. Install the packages:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# zypper --quiet --non-interactive install
|
||||
|
||||
.. include:: common_configure.rst
|
||||
|
||||
|
||||
Finalize installation
|
||||
---------------------
|
||||
|
||||
Start the whereto services and configure them to start when
|
||||
the system boots:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl enable openstack-whereto-api.service
|
||||
|
||||
# systemctl start openstack-whereto-api.service
|
||||
@ -1,33 +0,0 @@
|
||||
.. _install-rdo:
|
||||
|
||||
Install and configure for Red Hat Enterprise Linux and CentOS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
This section describes how to install and configure the whereto service
|
||||
for Red Hat Enterprise Linux 7 and CentOS 7.
|
||||
|
||||
.. include:: common_prerequisites.rst
|
||||
|
||||
Install and configure components
|
||||
--------------------------------
|
||||
|
||||
#. Install the packages:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# yum install
|
||||
|
||||
.. include:: common_configure.rst
|
||||
|
||||
Finalize installation
|
||||
---------------------
|
||||
|
||||
Start the whereto services and configure them to start when
|
||||
the system boots:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl enable openstack-whereto-api.service
|
||||
|
||||
# systemctl start openstack-whereto-api.service
|
||||
@ -1,31 +0,0 @@
|
||||
.. _install-ubuntu:
|
||||
|
||||
Install and configure for Ubuntu
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section describes how to install and configure the whereto
|
||||
service for Ubuntu 14.04 (LTS).
|
||||
|
||||
.. include:: common_prerequisites.rst
|
||||
|
||||
Install and configure components
|
||||
--------------------------------
|
||||
|
||||
#. Install the packages:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# apt-get update
|
||||
|
||||
# apt-get install
|
||||
|
||||
.. include:: common_configure.rst
|
||||
|
||||
Finalize installation
|
||||
---------------------
|
||||
|
||||
Restart the whereto services:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# service openstack-whereto-api restart
|
||||
@ -1,20 +0,0 @@
|
||||
.. _install:
|
||||
|
||||
Install and configure
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section describes how to install and configure the
|
||||
whereto service, code-named whereto, on the controller node.
|
||||
|
||||
This section assumes that you already have a working OpenStack
|
||||
environment with at least the following components installed:
|
||||
.. (add the appropriate services here and further notes)
|
||||
|
||||
Note that installation and configuration vary by distribution.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
install-obs.rst
|
||||
install-rdo.rst
|
||||
install-ubuntu.rst
|
||||
@ -1,9 +0,0 @@
|
||||
.. _next-steps:
|
||||
|
||||
Next steps
|
||||
~~~~~~~~~~
|
||||
|
||||
Your OpenStack environment now includes the whereto service.
|
||||
|
||||
To add additional services, see
|
||||
https://docs.openstack.org/project-install-guide/ocata/.
|
||||
@ -1,24 +0,0 @@
|
||||
.. _verify:
|
||||
|
||||
Verify operation
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Verify operation of the whereto service.
|
||||
|
||||
.. note::
|
||||
|
||||
Perform these commands on the controller node.
|
||||
|
||||
#. Source the ``admin`` project credentials to gain access to
|
||||
admin-only CLI commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ . admin-openrc
|
||||
|
||||
#. List service components to verify successful launch and registration
|
||||
of each process:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack whereto service list
|
||||
@ -1,7 +0,0 @@
|
||||
========
|
||||
Usage
|
||||
========
|
||||
|
||||
To use whereto in a project::
|
||||
|
||||
import whereto
|
||||
@ -1 +0,0 @@
|
||||
.. include:: ../../README.rst
|
||||
@ -1,5 +0,0 @@
|
||||
==========
|
||||
References
|
||||
==========
|
||||
|
||||
References of whereto.
|
||||
@ -2,4 +2,47 @@
|
||||
Users guide
|
||||
===========
|
||||
|
||||
Users guide of whereto.
|
||||
To test a set of redirects, ``whereto`` needs the input ``.htaccess``
|
||||
file and another input file with test data.
|
||||
|
||||
The ``.htaccess`` file should contain ``Redirect`` and
|
||||
``RedirectMatch`` directives. Blank lines and lines starting with
|
||||
``#`` are ignored. For example, this input includes 6 rules:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Redirect old top-level HTML pages to the version under most recent
|
||||
# full release.
|
||||
redirectmatch 301 ^/$ /pike/
|
||||
redirectmatch 301 ^/index.html$ /pike/
|
||||
redirectmatch 301 ^/openstack-projects.html$ /pike/projects.html
|
||||
redirectmatch 301 ^/language-bindings.html$ /pike/language-bindings.html
|
||||
|
||||
# Redirect docs.openstack.org index.html subpage pointers to main page
|
||||
redirect 301 /install/ /pike/install/
|
||||
redirect 301 /basic-install/ /pike/install/
|
||||
|
||||
The test data file should include one test per line, including 3
|
||||
parts: the input path, the expected HTTP response code, and the
|
||||
expected output path. For example:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
/ 301 /pike/
|
||||
/ 301 /pike
|
||||
/install/ 301 /pike/install/
|
||||
/no/rule 301 /should/fail
|
||||
|
||||
The output from ``whereto`` includes a report of any tests that do not
|
||||
match, including if no rules match and if multiple rules match. For
|
||||
example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ whereto -q --ignore-untested .htaccess test.txt
|
||||
|
||||
Test on line 2 did not produce expected result: / 301 /pike
|
||||
[7] redirectmatch 301 ^/$ /pike/
|
||||
No rule matched test on line 4: /no/rule 301 /should/fail
|
||||
|
||||
2 failures
|
||||
|
||||
@ -13,3 +13,5 @@ testtools>=1.4.0 # MIT
|
||||
openstackdocstheme>=1.11.0 # Apache-2.0
|
||||
# releasenotes
|
||||
reno>=1.8.0 # Apache-2.0
|
||||
|
||||
sphinxcontrib.autoprogram
|
||||
|
||||
3
tox.ini
3
tox.ini
@ -24,7 +24,8 @@ commands = {posargs}
|
||||
commands = python setup.py test --coverage --testr-args='{posargs}'
|
||||
|
||||
[testenv:docs]
|
||||
commands = python setup.py build_sphinx
|
||||
basepython = python3
|
||||
commands = python3 setup.py build_sphinx
|
||||
|
||||
[testenv:releasenotes]
|
||||
commands =
|
||||
|
||||
@ -55,37 +55,41 @@ def process_tests(ruleset, tests):
|
||||
return (mismatches, untested)
|
||||
|
||||
|
||||
# This is constructed outside of the main() function to support
|
||||
# sphinxcontrib.autoprogram in the doc build.
|
||||
argument_parser = argparse.ArgumentParser()
|
||||
group = argument_parser.add_mutually_exclusive_group()
|
||||
group.add_argument(
|
||||
'--ignore-untested',
|
||||
action='store_false',
|
||||
dest='error_untested',
|
||||
default=True,
|
||||
help='ignore untested rules',
|
||||
)
|
||||
group.add_argument(
|
||||
'--error-untested',
|
||||
action='store_true',
|
||||
dest='error_untested',
|
||||
help='error if there are untested rules',
|
||||
)
|
||||
argument_parser.add_argument(
|
||||
'-q', '--quiet',
|
||||
action='store_true',
|
||||
default=False,
|
||||
help='run quietly',
|
||||
)
|
||||
argument_parser.add_argument(
|
||||
'htaccess_file',
|
||||
help='file with rewrite rules',
|
||||
)
|
||||
argument_parser.add_argument(
|
||||
'test_file',
|
||||
help='file with test data',
|
||||
)
|
||||
|
||||
|
||||
def main():
|
||||
arg_parser = argparse.ArgumentParser()
|
||||
group = arg_parser.add_mutually_exclusive_group()
|
||||
group.add_argument(
|
||||
'--ignore-untested',
|
||||
action='store_false',
|
||||
dest='error_untested',
|
||||
default=True,
|
||||
help='ignore untested rules',
|
||||
)
|
||||
group.add_argument(
|
||||
'--error-untested',
|
||||
action='store_true',
|
||||
dest='error_untested',
|
||||
help='error if there are untested rules',
|
||||
)
|
||||
arg_parser.add_argument(
|
||||
'-q', '--quiet',
|
||||
action='store_true',
|
||||
default=False,
|
||||
help='run quietly',
|
||||
)
|
||||
arg_parser.add_argument(
|
||||
'htaccess_file',
|
||||
help='file with rewrite rules',
|
||||
)
|
||||
arg_parser.add_argument(
|
||||
'test_file',
|
||||
help='file with test data',
|
||||
)
|
||||
args = arg_parser.parse_args()
|
||||
args = argument_parser.parse_args()
|
||||
|
||||
ruleset = rules.RuleSet()
|
||||
with io.open(args.htaccess_file, 'r', encoding='utf-8') as f:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user