Resize and cold migrate can be confusing since they are
very similar operations and share mostly the same code paths
but there are some notable differences. This adds a contributor
doc, similar to the evacuate-vs-rebuild contributor doc, to
try and explain things at a high level and provide enough links
so contributors can follow along and see where things fit into
the puzzle.
A sequence diagram is sorely needed for this as well but that will
come in a separate change.
Change-Id: I11b401a3f874226fdc20a0ee0bd518192f70fa1d
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
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
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
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
openstack-dev was decomissioned this night in https://review.openstack.org/621258
Update openstack-dev to openstack-discuss
Change-Id: If51f5d5eb710e06216f6d6981a70d70b6b5783cc
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
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
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
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
Balazs Gibizer