This is a follow-up patch for https://review.opendev.org/676730.
In the TOC of the current PDF file [1], most contents related to
user and admin guides are located under "For Contributors" section.
This is weird. It happens because the latex builder constructs
the document tree based on "toctree" directives even though they
are marked as "hidden".
This commit reorganizes "toctree" per section.
The "toctree" directives must be placed at the end of
individual sections. Otherwise, content of a last section and
content just after "toctree" directive are concatenated
into a same section in the rendered LaTeX document.
This commit also improves the following as well:
* Specify "openany" as "extraclassoptions" to skip blank pages
along with "oneside" to use same page style for odd and even pages.
* Set "tocdepth" and "secnumdepth" to 3 respectively.
"tocdepth" controls the depth of TOC and "secnumdepth" controls
the level of numbered sections in TOC.
Note that this commit does not reorganize file structure under doc/source.
I believe this should be done separately.
[1] https://docs.openstack.org/nova/latest/doc-nova.pdf
Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c
Story: 2006100
Task: 35140
These closely related features are the source of a disproportionate
number of bugs and a large amount of confusion among users. The spread
of information around multiple docs probably doesn't help matters.
Do what we've already done for the metadata service and remote consoles
and clean these docs up. There are a number of important changes:
- All documentation related to host aggregates and availability zones is
placed in one of three documents, '/user/availability-zones',
'/admin/aggregates' and '/admin/availability-zones'. (note that there
is no '/user/aggregates' document since this is not user-facing)
- References to these features are updated to point to the new location
- A glossary is added. Currently this only contains definitions for host
aggregates and availability zones
- nova CLI commands are replaced with their openstack CLI counterparts
- Some gaps in related documentation are closed
Change-Id: If847b0085dbfb4c813d4a8d14d99346f8252bc19
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
People often get confused about the differences between
evacuate and rebuild operations, especially since the
conductor and compute methods are both called "rebuild_instance".
This change adds a contributor document which explains some
of the high and low level differences between the two operations.
Change-Id: I146fbc65237c4729ce3c28a4614589ba085dfce0
Closes-Bug: #1843439
Added reference documentation and release note to explain how filtering
of hosts by isolate aggregates works.
Change-Id: I8d8086973039308f9041a36463a834b5275708e3
Implements: blueprint placement-req-filter-forbidden-aggregates
The conductor doc is not really end user material,
so this moves it under reference/, removes it from the
user page and adds it to the reference index for internals.
Also makes the contributor page link to the reference internals
since it's kind of weird to have one contributor section that
only mentions one thing but the internals under reference have
a lot more of that kind of detail. Finally, a todo is added so
we don't forget to update the reference internals about versioned
objects at some point since that's always a point of confusion
for people.
Change-Id: I8d3dbce5334afaa3e1ca309b2669eff9933a0104
Profiling eventlet using services is a bit different from standard
situations so here is a document that tries to explain the basics
on how to get started doing it.
Change-Id: If8c34653285f07c5cc1abccabfec16f18daafdde
The api documentation is now published on docs.openstack.org instead
of developer.openstack.org. Update all links that are changed to the
new location.
Note that Neutron publishes to api-ref/network, not networking anymore.
Note that redirects will be set up as well but let's point now to the
new location.
For details, see:
http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007828.html
Change-Id: Id2cf3aa252df6db46575b5988e4937ecfc6792bb
Turns out we've a *lot* of disparate metadata systems. Attempt to both
link them somewhat through extensive cross-referencing and extract out
deployment-specific stuff from user-facing docs. Lots of changes here,
but in summary:
- Split out admin-focused content from the metadata API, config drive,
user data and vendordata docs.
- Merge the config drive, metadata service, vendordata and user-data
user docs, which are mostly talking about the same thing and are
fairly barren without the deployment components
- Make use of various oslo.config and Sphinx roles
Side note: I miss when we have tech writers to do this stuff for us :(
Change-Id: I4fb2b628bd93358a752e2397ae353221758e2984
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
This adds a testing guide for creating a down cell
environment with a basic single-node devstack setup.
Change-Id: I8c021129a4df914f56193cca9ff136390a7240c3
This is a guide I used to help me throughout the cycle and I'm
proposing it to the docs, in case it might help someone.
Change-Id: I4f7600c908bf90395515f690b8eee0f9e7b0c9b0
Remove links to internal placement documentation. Instead indicate
that placement is required by nova, and point elsewhere.
The depends-on adds placement install docs to the placement repo.
Depends-On: https://review.openstack.org/628220
Change-Id: I9f0d52e7b46b270363946211cf6dc0c338981cb2
The Placement REST API Version History page has been
created by splitting the Placement doc top page (index.html)
since I66e0c7d18b253b0a5a8fdac65e30b5b3cef37db2.
So the link to the Placement REST API Version History
is updated in the nova doc.
Change-Id: I60701b09ade203b35d4d1281eb32b177543c064a
Placement documents have been published since
I667387ec262680af899a628520c107fa0d4eec24.
So use links to placement documents
https://docs.openstack.org/placement/latest/
in nova documents.
Change-Id: I218a6d11fea934e8991e41b4b36203c6ba3e3dbf
This adds some background, guidelines and structural
notes on writing nova-status upgrade checks.
This is intentionally written with some potentially
redundant information or nova developers as it's
also meant to be consumed outside nova as part of the
community-wide "upgrade-checkers" goal for Stein [1].
Story: 2003570
[1] https://governance.openstack.org/tc/goals/stein/upgrade-checkers.html
Change-Id: I340b25edeab3ac19c5d0bedfc69acd037d57bdd2
Scheduler hints are not really documented very well at all except
for being mentioned per scheduler filter in the admin configuration
guide, nor are they documented within relation to flavor extra
specs which are both used for impacting scheduling decisions and
are choices that a deployer has to make based on how they configure
their cloud.
This change adds a document about scheduler hints and how they are
similar to and different from flavor extra specs, including end
user discoverability and interoperability, and thoughts on which
should be used if writing a custom scheduler filter.
The TODO in the API guide is also resolved by linking to this
document.
Change-Id: Ib1f35baacf59efafb9e4bccfcc4f0025d99ad5b2
The top level index (home page) was duplicating the
configuration/index content, so this simply changes
the home page into a table of contents for the configuration
sub-tree and leaves the config/policy content in the
sub-tree. This will be needed when we add docs about
placement policy.
The hidden configuration toc tree items are moved
into the sub-tree configuration/index to be closer
to the actual documents we're hiding from the toc tree.
Related to blueprint granular-placement-policy
Change-Id: Iad87dc339278ee7e7cf8de5eea252bbb7a5f75c2
This ensures we have version-specific references to other projects [1].
Note that this doesn't mean the URLs are actually valid - we need to do
more work (linkcheck?) here, but it's an improvement nonetheless.
[1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper
Change-Id: Ifb99e727110c4904a85bc4a13366c2cae300b8df
this document is out of date since a set of changes made such as
43f91a87cb39f6159bde8be8d02aa7
Put those 'to be fixed in queens' make people think it should
be already been fixed due to queen release, so remove them in order
to avoid confusion and we can continue to enhance this doc.
TrivialFix
Change-Id: I12dd385f4e1f159bdb9a78a629d4095889397c09
In 'Writing to the API' section of nova doc index page(*),
there is the 'Compute API Guide::' item.
It should be 'Compute API Guide:'.
* https://docs.openstack.org/nova/latest/#writing-to-the-api
TrivialFix
Change-Id: I59455c9783baccbf6ca7c6cf9da7f040f235de14
This imports the "launch instance" end user guide docs from
the openstack-manuals repo. As part of the docs migration
in Pike, these were forgotten. The copied contents come from
the stable/ocata branch of openstack-manuals, and therefore
likely need some updating, but that could be done in follow up
changes. This is an initial import to (1) publish the content
again somewhere and (2) fix broken links in the cinder docs
for booting from volume.
Change-Id: Ie039322660fd0e2e0403843448379b78114c425b
Partial-Bug: #1714017
Related-Bug: #1711267
This imports the "provide-user-data-to-instances" page
from the old openstack-manuals user guide.
Since we don't have a glossary, the :term: link is removed
and replaced with just giving the glossary definition as
the first part of the doc.
Change-Id: Iae70d9b53d6cefb3bcb107fe68499cccb71fc15e
Partial-Bug: #1714017
As part of the docs migration from openstack-manuals to
nova in the pike release we missed the config-drive docs.
This change does the following:
1. Imports the config-drive doc into the user guide.
2. Fixes a broken link to the metadata service in the doc.
3. Removes a note about liberty being the current release.
4. Adds a link in the API reference parameters to actually
point at the document we have in tree now, which is
otherwise not very discoverable as the main index does
not link to this page (or the user index for that matter).
Partial-Bug: #1714017
Closes-Bug: #1720873
Change-Id: I1d54e1f5a1a94e9821efad99b7fa430bd8fece0a
Underscores make for really ugly URLs and every other document here is
now using hyphens for this very reason. Let's try to keep that going.
Change-Id: I5c99ff6b04ee97bac210a0d6762015225775c5ee
There are currently two docs describing flavors in 'admin', which
contain a lot of overlapping information. Fix this by keeping the
configuration guide (how to create, delete, modify flavors) in
'admin', while moving the reference-style parts into 'user'. We
cross-reference the two internally.
Given that large chunks of this needed to be rewritten, we've taken the
opportunity to fix a poor description for the RXTX factor, closing a
longstanding bug in the process.
Change-Id: Ia57c93ef1e72ccf134ba6fc7fcb85ab228d68a47
Closes-Bug: #1688054
We haven't had a doc wide index or mod index in this
section on the main page for a long time, so it's a
weird title for just having a link to the search page.
This renames the section title, describes the link and
also links to the openstack-wide docs search page.
Change-Id: Idf63e6035841c8ff0ec1aa9bd2994fedf53555b1
The idea is that each guide should be self contained, even though we can
link between them. Enforce this by duplicating a lot of the content from
the main index page to the user index page.
Change-Id: I160fed0f1b507eba7958666bf38f4138b0f62b3a
Notifications are essentially another API for end users, but
it can be hard to find the list of existing notifications or
their samples which are buried deep down via contributors >
technical reference deep dive > notitfications. If I'm an
end user, I'd like to just see them in the same set of links
on the main page as the API, under the "For End Users" section.
Change-Id: If3ca21b080d06a291ed27c9bcd84a566164c3b70
Now that we have a placement api-ref getting published, we
should link to it like we do for the compute api-ref. This
also links in the placement microversion history for consistency.
Change-Id: Id0c70486c5a72a4d6794d80d350a45a5f356ca37
There have been some major changes to how scheduling works in Nova
during the Pike and Queens cycles. This documents these design changes
so that this new, more complex workflow is clearly spelled out.
Co-Authored-By: Ed Leafe <ed@leafe.com>
Change-Id: I15121d8fe9b715c0aec39dee4bfdf25ced42b481
Per comments in I6815958b2533d462a2e5d27e7be57440d9f4f40a and
I5fdafd9f6cf07a19bf86a6343663dad410887dcb.
Part of bp: doc-migration
Change-Id: Iac833503b57386ab91fa86f8c48f0dd8039e5922
Missing from our contributor guides is documentation guidelines,
starting a page there for now especially as there are a couple of
things that emerged in the great pike import that would be good to
write down.
Part of bp: doc-migration
Change-Id: Ib2b49f70c55311195535a5ef250ff555e227fa0a
Import the following files from the former config-reference [1]:
api.rst
cells.rst
fibre-channel.rst
hypervisor-basics.rst
hypervisor-hyper-v.rst
hypervisor-kvm.rst
hypervisor-lxc.rst
hypervisor-qemu.rst
hypervisor-virtuozzo.rst
hypervisor-vmware.rst
hypervisor-xen-api.rst
hypervisor-xen-libvirt.rst
hypervisors.rst
index.rst
iscsi-offload.rst
logs.rst
resize.rst
samples/api-paste.ini.rst
samples/index.rst
samples/policy.yaml.rst
samples/rootwrap.conf.rst
schedulers.rst
The below files are skipped as they're already included, in slightly
different forms, in the nova documentation.
config-options.rst
nova-conf-samples.rst
nova-conf.rst
nova.conf
Part of bp: doc-migration
Change-Id: I145e38149bf20a5e068f8cfe913f90c7ebeaad36
The index previously was written for the developer docs, but this is
more than developer docs now. That also means this is the general
google landing page for people, so a basic "what is nova" is
appropriate.
Part of bp: doc-migration
Change-Id: I5fdafd9f6cf07a19bf86a6343663dad410887dcb
This attempts to reorganize the front page content relevant to
operators into digestable chunks, including some summaries of links to
explain to people why they might want to follow those links to learn
more.
Part of bp: doc-migration
Change-Id: I6815958b2533d462a2e5d27e7be57440d9f4f40a
This reorganizes the pieces that are for end users into a convenient
chunk up front in the main index page.
Part of bp: doc-migration
Change-Id: Ic2fcabbf3faa531fccb19cffa2564f005142e463
In an attempt to make the main navigation sidebar not be visual mud
(and really confusing) create a reference sub page that explains all
the references.
Part of bp: doc-migration
Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
In order to wrangle together a top level TOC that makes sense, stop
including everything in the TOC (ideally we could convince sphinx to
not warn on that).
This creates a Contributor Documentation landing page with deep links
to all the relevant documents. It removes all those links from the
front page, and the TOC. They can be found by deep links or search,
and it is a less confusing initial experience for folks.
Part of bp: doc-migration
Change-Id: If5e7940ddd0ae3316f7475742c02abfe3df28ac4
Import all docs from openstack-manuals.
Part of bp: doc-migration
Change-Id: I28bb8ce1f4a8653f176a554d2e95b4423c437972
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
Import all docs from openstack-manuals.
Part of bp: doc-migration
Change-Id: If1fa15f5495a8a207042e7a43d34d32671c59ee1
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
Balazs Gibizer