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
|
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 coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||||
extensions = [
|
extensions = [
|
||||||
'sphinx.ext.autodoc',
|
'sphinx.ext.autodoc',
|
||||||
'openstackdocstheme',
|
'sphinxcontrib.autoprogram',
|
||||||
#'sphinx.ext.intersphinx',
|
#'sphinx.ext.intersphinx',
|
||||||
]
|
]
|
||||||
|
|
||||||
@ -40,11 +40,6 @@ master_doc = 'index'
|
|||||||
project = u'whereto'
|
project = u'whereto'
|
||||||
copyright = u'2017, OpenStack Developers'
|
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.
|
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||||
add_function_parentheses = True
|
add_function_parentheses = True
|
||||||
|
|
||||||
@ -62,7 +57,7 @@ pygments_style = 'sphinx'
|
|||||||
# html_theme_path = ["."]
|
# html_theme_path = ["."]
|
||||||
# html_theme = '_theme'
|
# html_theme = '_theme'
|
||||||
# html_static_path = ['static']
|
# html_static_path = ['static']
|
||||||
html_theme = 'openstackdocs'
|
html_theme = 'nature'
|
||||||
|
|
||||||
# Output file base name for HTML help builder.
|
# Output file base name for HTML help builder.
|
||||||
htmlhelp_basename = '%sdoc' % project
|
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
|
Contributor Documentation
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
.. toctree::
|
.. include:: ../../../CONTRIBUTING.rst
|
||||||
:maxdepth: 2
|
|
||||||
|
|
||||||
contributing
|
|
||||||
|
|
||||||
|
|||||||
@ -3,24 +3,24 @@
|
|||||||
You can adapt this file completely to your liking, but it should at least
|
You can adapt this file completely to your liking, but it should at least
|
||||||
contain the root `toctree` directive.
|
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::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
readme
|
|
||||||
install/index
|
install/index
|
||||||
library/index
|
|
||||||
contributor/index
|
contributor/index
|
||||||
configuration/index
|
|
||||||
cli/index
|
cli/index
|
||||||
user/index
|
user/index
|
||||||
admin/index
|
|
||||||
reference/index
|
|
||||||
|
|
||||||
Indices and tables
|
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::
|
The whereto package should be installed via ``pip``:
|
||||||
:maxdepth: 2
|
|
||||||
|
|
||||||
get_started.rst
|
.. code-block:: console
|
||||||
install.rst
|
|
||||||
verify.rst
|
|
||||||
next-steps.rst
|
|
||||||
|
|
||||||
The whereto service (whereto) provides...
|
$ pip install whereto
|
||||||
|
|
||||||
This chapter assumes a working setup of OpenStack following the
|
|
||||||
`OpenStack Installation Tutorial
|
|
||||||
<https://docs.openstack.org/project-install-guide/ocata/>`_.
|
|
||||||
|
|||||||
@ -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
|
||||||
===========
|
===========
|
||||||
|
|
||||||
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
|
openstackdocstheme>=1.11.0 # Apache-2.0
|
||||||
# releasenotes
|
# releasenotes
|
||||||
reno>=1.8.0 # Apache-2.0
|
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}'
|
commands = python setup.py test --coverage --testr-args='{posargs}'
|
||||||
|
|
||||||
[testenv:docs]
|
[testenv:docs]
|
||||||
commands = python setup.py build_sphinx
|
basepython = python3
|
||||||
|
commands = python3 setup.py build_sphinx
|
||||||
|
|
||||||
[testenv:releasenotes]
|
[testenv:releasenotes]
|
||||||
commands =
|
commands =
|
||||||
|
|||||||
@ -55,37 +55,41 @@ def process_tests(ruleset, tests):
|
|||||||
return (mismatches, untested)
|
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():
|
def main():
|
||||||
arg_parser = argparse.ArgumentParser()
|
args = argument_parser.parse_args()
|
||||||
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()
|
|
||||||
|
|
||||||
ruleset = rules.RuleSet()
|
ruleset = rules.RuleSet()
|
||||||
with io.open(args.htaccess_file, 'r', encoding='utf-8') as f:
|
with io.open(args.htaccess_file, 'r', encoding='utf-8') as f:
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user