The global module documentation is no longer being generated
and the link points to a non-existent document.
The purpose of global module documentation is now fulfilled by
the automatically generated class, and function level reference
documents which are linked properly.
As such there is no need to keep the link around, or to
reestablish module level documentation.
Signed-off-by: Jiri Podivin <jpodivin@redhat.com>
Change-Id: I05e5144a36f33aa5feb996964d1a098b1716cf6a
PrettyTable was capped at a < 0.8, which meant we were getting the
veritably ancient 0.7.2 release first release in April 2013 (!) [1].
The project is now being maintained as a Jazzband project [2], meaning
we should switch to this new version.
The only significant change required here is that we no longer set the
'min_width' attribute since that actually does something - the wrong
thing - now. We want this attribute to set a lower bound on the wrap
width as opposed to an absolute minimum we can use, which is what
setting the 'min_width' attribute would do.
While we're here, we also remove a now useless bit of Python 2 code and
bump cmd2 to a slightly newer version.
[1] https://pypi.org/project/prettytable/#history
[2] https://github.com/jazzband/prettytable
Change-Id: Iceac729e7a9429e8ab25c60524a48d0aaeebeb37
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Depends-On: https://review.opendev.org/c/openstack/requirements/+/774917
There were some in both the docs and the demo application.
Change-Id: I58d14cd3a372f9bdf617cbfbcb5ce34169ac83f8
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
With the advent of importlib, entry points are no long a setuptools-only
thing. Update the docs to reflect that.
Change-Id: I099f397ddb4d71879597cfe67ef2a1eff4a8d1af
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Switch to openstackdocstheme 2.2.1 version. Using
this version will allow especially:
* Linking from HTML to PDF document
* Allow parallel building of documents
* Fix some rendering problems
Update Sphinx version as well.
Disable openstackdocs_auto_name to use 'project' variable as name.
Change pygments_style to 'native' since old theme version always used
'native' and the theme now respects the setting and using 'sphinx' can
lead to some strange rendering.
openstackdocstheme renames some variables, so follow the renames
before the next release removes them. A couple of variables are also
not needed anymore, remove them.
See also
http://lists.openstack.org/pipermail/openstack-discuss/2020-May/014971.html
Change-Id: I50caba24ba8d458e5061cf412b8f59e3815c58f7
This allows consumers to let cliff know who they are, so the
autoprogram-sphinx directive doesn't produce messages like
This command is provided by the $me plugin.
Change-Id: I2d5a527910ddc64f83d0cba39c584b8b05a299b7
MANIFEST files aren't needed when using pbr, while the Makefiles have
since been replace by infra's release tooling (for release) and tox (for
docs).
Change-Id: I2a7ac86c8a9b07fe6e35be1f0ac552ef77d17bfd
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Put these in place as a setup for the new versions of the doc build
jobs. Keep using them from the normal dep list until the jobs are
changed.
While we're here, update the docs env to use sphinx-build instead of
python setup.py build_sphinx. Also add python2.7 to the docs env, since
I accidentally tried building it with my python3 tox and it blew up
substantially.
Change-Id: I0fcc50c4c396758e839c329ce786a6f609bb1342
Remove the dependency on the demoapp and just add it to the import
path so it is available to be imported. Copy the entry point settings
into the main cliff setup.cfg to ensure they are registered for the
doc build to find.
Change-Id: I390410bc5247e8b6c8d0a8fec8e7ecb223d8d6c1
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit adds a feature to generate a reference of global
optoions of a cliff application to autoprogram-cliff directive.
If a class path of a cliff application is specified as the argument of
autoprogram-cliff directive, it will be interpreted as a cliff application
and global options of the specified application are rendered.
Change-Id: I20e46521a137ca721fae28f10c5cf75d26069e45
We have no way to check the cliff sphinxext work expectedly now.
It would be useful if we can check the cliff sphinxext in our doc.
Change-Id: If0578460dd678ffd33c20cf3707c08fa637eaf87
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
This patch adds some minor information that also
should be taken into account while integrate sphinx
Change-Id: I0f88b96a5858ce27ad330a647255c11762dd413a
cliff is a library that is used outside of OpenStack, too. Having
a build requirement that needs something OpenStack specific makes
life in cases (eg. for downstream packagers) more difficult.
So let's make openstackdocstheme an optional requirement.
Change-Id: I0f94a431be083b8b4baec850b1885ba07b5bf5c2
* We have a long index in user/index page, as the history page
has a lot of sections. It loses the readability in general.
Let's use maxdepth 1 for history in the toctree directive.
* Remove unnecessary vertical line for quote blocks.
openstackdocstheme shows a vertial line for quote blocks.
If we have unnecessary leading spaces, the vertical line are shown.
This cleans up such spaces in user/sphinxext.rst.
Change-Id: I913d23cc6148d37d28c27c4f3a40b5a6225dac76
1) Update doc links according to OpenStack document migration
2) Use https instead of http for docs links
Change-Id: I0af218e58e32a06b7bd9cef661fc75f801689323
In some cases, a single documentation build wants to handle multiple
cliff-based CLI. One possible example is openstack-manuals CLI ref.
In this case, the global setting 'autoprogram_cliff_application'
does not work. It is nice if we can specify an application name
per autoprogram-cliff directive.
This commit introduces a new option 'application' to
autoprogram-cliff directive to allow this.
Change-Id: Ie2d01920dc04f2a92031a641d809f7da8af8b395
Set some of the new config values and enable openstackdocstheme as an
extension so it will inject values into the page context as it writes
each documentation page. This ensures the pages link to the right bug
tracker, etc.
Change-Id: I0bc0f1c42e1e54af0dc29d7dfcb23293a3347723
Depends-On: Icf3a40ed104cfd828f532f6f2b112ed02f996ff5
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
Add hooks that are called before and after the take_action() method of
the command.
Change-Id: Id6527dfe0946c0ab169fc165b84d40f3ff95e08c
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
Update Commands to load a separate set of extensions to be used as
"hooks," triggered at different points in the processing of the
command. Start with a hook that is given access to the argument parser
for the command so it can modify it.
Change-Id: I0785548fd36a61cda616921a4a21be3f67701300
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
At the moment, the help action (-h, --help) is ignored by default.
However, there is merit in being able to ignore further options. Make it
so.
Change-Id: I924d89fd6b602accac90604a3427b19bd4f9777a
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Many projects, such as 'python-openstackclient', manually write
documentation for their cliff-based command line tools. In many cases,
this documentation is a 1:1 reflection of what one could build from the
command line. This is unnecessary overhead that could and should be
avoided.
Add an 'autoprogram-cliff' directive that will allow folks to
automatically document their command line tools.
Change-Id: I497e62382768ffc9668a103706001735a7d851ff
This change replaces the cliff-tablib json formatter with an internal
replacement. It differs from the tablib formatter in the following ways:
- by default outputs with an indent of 2 spaces. The --noindent formatting
argument outputs with no indentation, to save space or to pipe to tools
which can't handle multi-line input.
- emit_one serialises a simple dict where the column name is the key
and the data item is the value (rather than a list of dicts with
'Field' and 'Value' keys)
The cliff release which contains this change will need a corresponding
cliff-tablib release which removes the json formatter from its setup.py
entry_points.
Change-Id: I7f9b1f339d96ead347a0c9d95ec7004a78d8c9d5
Related-Bug: #1308744
This change replaces the cliff-tablib yaml formatter with an internal
replacement. It differs from the tablib formatter in the following ways:
- always outputs with block formatting rather than the PyYAML default
of deciding based on value content
- emit_one serialises a simple dict where the column name is the key
and the data item is the value (rather than a list of dicts with
'Field' and 'Value' keys)
- emit_one preserves column order by printing a single-item dict for
each column_name
The cliff release which contains this change will need a corresponding
cliff-tablib release which removes the yaml formatter from its setup.py
entry_points.
Change-Id: I691dbab3dee7c5ec28b1083f87ab1f5c051d582b
Related-Bug: #1308744
Help messages are in normally fully sentences starting with a capital
letter, some of the help messages follow this but not all. Adjust all so
that help messages look consistent.
Also, improve wording of --help text.
Change-Id: Ia22ccc42d71a4c9d7085303939dae9948ba52418
pbr generates a changelog for us, and since we haven't been keeping up
with doing that manually for all releases just go ahead and include the
one pbr generates.
Change-Id: I6f166dc01beeb3feafb3839d3c92e31798c2caf1