b5abe27025
I started with the "Preparing the MOS Deployment" table
The hardware setup steps have been moved to the Install Guide in another CM
Added a few issues that were not spelled out
Set up separate sections to hold the discussions for each issue.
"Network Topologies" cross-references architectural information in ref-arch
* Andrey Danin provided the "advice"
* Restructuring the network docs became necessary to make this work. To whit:
For Neutron, various structural modifications were required;
no substantive content modifications were made
* Added a couple headers and tags to ref-arch for Neutron topologies
* Deleted files from pre-install/0051-network-plan/topology:
* 0710-neutron-topologies.rst -- header only, no longer required
* 0720-neutron-vlan.rst -- duplicates info in ref-arch/neutron-intro/\
0210-vlan.rst; this had a couple sentences at the end that weren't in
ref-arch so I moved those over
* 0730-neutron-gre.rst -- duplicates info in ref-arch/neutron-intro/\
0220-gre.rst; this had a couple sentences at the end that weren't in
ref-arch so I moved those over
* 0760-neutron-vlan-plan.rst and 0780-neutron-gre-plan.rst were pulled
into ref-arch/0260-neutron-config.rst. Yes, this leaves one file with
three headers in it but, when we deal with the content, these pieces
need to be considered together
* pre-install/0051-network-plan/topology/0700-neutron.rst just sourced the
above files so is deleted
For Nova, moved the nova-network topology info from pre-install to ref-arch
to parallel the Neutron section we set up there.
* The following files from pre-installation/0051-network-plan/topology/nova
are now in reference-architecture/nova-intro and sourced from the
6070-nova-topologies.rst file in reference-architecture. Section titles
are also modified to include "Nova-network" to improve readability:
- 0620-nova-flat-dhcp.rst
- 0630-nova-vlan.rst
- 0659-nova-net-plan.rst
- 0660-nova-plan-flatdhcp.rst
- 0680-plan-vlan.rst
- [ignore 0650-nova-assign-networks-to-nics.rst -- it is going to User Guide]
* Other files from this directory are disposed of as follows:
- 0610-nova-topologies -- sourced ino ref-arch/6070-nova-topologies.rst
(top file of nova section in ref-arch)
- 0650-nova-assign-networks-to-nics.rst -- material is obsolete and done
better in other files now included in user-guide.
* The following files from pre-install/0051-network-plan/0100-netconfig-options are deleted:
- 0100-netconfig-options (header/intro info no longer needed)
- 0110- (info pulled into
- 0200 - sourced files below it that are moved and sourced elsewhere
The same sections that discussed the topologies had information about
routers and switches. I'm not exactly sure where the best place is
for this but, for now, I'm putting it in ref-arch right after the write-up
about Public and Floating IPs. Alas, that is in a different commit, and
that other commit creates a sub-directory where these files should go.
So, for now, I created two files in the main ref-arch directory; I will
move these into the proper place after everything is merged.
* 6030-router is based on install-guide/0070-networks/350-router.rst,
with content also pulled in from pre-install/0051-network-plan/topology/\
0900-routing-req.rst. I did some rewriting but the content is unchanged.
This includes a bunch of Fuel screen shots that I think are superfluous
but I need to compare them to the rewritten User Guide; I may need to do
some moving or xref'ing of information.
* 6034-switch.rst is renamed from install-guide/0070-networks/
300-switch-config.rst. I did a bit of editing but the content is
unchanged.
* I had to tag the files with sample switch configurations so I could
link to them. I also prefaced each of those titles with either "Nova-network"
or "Neutron".
* After the above, the following files are deleted:
* pre-install/0051-network-plan/topology/0900-routing-req (included in
new routing document)
* pre-install/0051-network-plan/0200-topology-include.rst -- included files
that are deleted or moved
* pre-install/0051-network-plan.rst -- included files that are deleted
or moved
ref-arch/0030-cluster-sizing.rst is deleted; its content was pulled into
pre-install/nodes-roles.rst. I added a bit of intro material; the substantive
content is unchanged.
pages/pre-install-guide/4000-plan0summary.rst was a bogus file; is deleted
At Patch 6, I deleted the screen shots from 0060-quick-start-instart-fuel;
this info doesn't belong here anyhow. I also right-aligned the diagrams in
the Examples and fixed the header levels for the examples at the end of the
document.
Change-Id: Ia4e68200bea2166d48d7691f80cc921459a337ff
Mirantis OpenStack Documentation
This repository contains the Mirantis OpenStack user and administrator guides. For more details, see the Mirantis OpenStack portal.
Contributing
We welcome all people who are interested in helping our Documentation team to improve our documentation. There are no formal membership requirements, so feel free to hop in. The best way to contibute is to fork our repository, do your changes and send us a Pull Request. You are invited to contribute any type of contribution like new ideas, testing, and even deployment scripts.
We also have an IRC channel at #fuel & #fuel-dev on irc.freenode.net
where you can ask questions and give feedback.
Prerequisites
Sphinx Documentation Generator must be installed to build the documentation. Please note that easy_install is a component of Python's Setup Tools package, which is commonly an optional install on most distributions.
To get started, you need to install all necesasary tools:
sudo apt-get install git python-pip python-dev make imagemagick libjpeg-dev inkscape
Among other things that installs ImageMagick and Inkscape.
And Sphinx necessary extensions:
sudo pip install -r requirements.txt
In addition to these eggs you will need to install PlantUML
To install PlantUML run this wget process:
sudo wget \
http://sourceforge.net/projects/plantuml/files/plantuml.jar/download \
-O /sbin/plantuml.jar
PlantumUML requires java: sudo apt-get install openjdk-7-jre
We use Inkscape to edit SVG images and convert them to PDF but you may use any other SVG-capable tool you like. We're not picky.
Building
To build a guide in HTML format, go to its directory and then run the
make command in that directory, like so:
make html
To generate the PDF file run this:
make pdf
You will find generated HTML documentation at:
_build/html
You will find generated PDF documentation at:
_build/pdf
Reviewer's Checklist
Checks for commit message:
-
The goal and extent of the change should be described in the commit message.
-
If the commit is related to a LaunchPad bug, it should have "Closes-Bug: nnnnnnn" line in the commit message. Likewise, "blueprint name-of-the-blueprint" for a commit related to a blueprint. Most non-trivial commits should have such references.
Checks for content changes:
-
For every block of content that is removed, there should be either a block that replaces it, or an explanation in the commit message why that block is no longer needed.
-
Confirm that the new content is approved by a technical expert in the relevant area.
-
Check that the content is in the right document and the right context. Deployment of Fuel itself is described in the Installation Guide; deployment of Mirantis OpenStack using Fuel, in User Guide; post-deployment operation of Mirantis OpenStack, in Operations Guide; and so on.
Checks for structural changes:
-
For any removed file (including original path in a move or rename), grep for the file name through all rst files and confirm that no stale references to the file are left behind.
-
For any added file (including new path in a move or rename), confirm that the new path is referenced in a way that will get it included in at least one document.
Testing the change locally:
-
Download the branch: git review -d
-
Check that it's based on the current tip of the master branch, look for "origin/master" next to commit hash in the output of: git log --graph --decorate
-
If it's not, check if it can be rebased onto master cleanly: git rebase --onto master HEAD^
-
Build HTML and PDF versions as described above. If rebase was necessary, build from the rebased version: you want to see what the result of the merge into master will look like
-
Check that the count of warnings reported by 'make pdf' hasn't increased relative to master.
-
Check that all sections touched by the change show up in the table of contents in the right place and at the right nesting level.
Finally, go through all changes line by line and ask yourself: what is the purpose of this change? Is that related to the description of the review given in the commit message? Could it be accidental or result of a merge error during rebase?