openstack/fuel-docs
Code Issues Proposed changes

Use SVG graphics in HTML docs

Browse Source 
* Pre-convert SVG images to PDF with Inkscape

 * Do not pre-convert SVG to JPG, let Sphinx choose the best image
   format (SVG or PDF)

 * Optimize diagram scaling for consistent font sizing and clean PDF
   layouts

Change-Id: I22285f5284f3c396ebe98392fca3dc731b01d6fa
This commit is contained in:
Dmitry Borodaenko
2013-12-11 17:00:56 -08:00
parent 0fea35a524
commit 6833250c86
15 changed files with 410 additions and 572 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -1,4 +1,5 @@
/_build
/_images/*_svg.png
/_images/*_svg.jpg
/_images/*.pdf
/.idea

21
Makefile
View File

@@ -15,9 +15,6 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
IMAGEDIRS = _images
SVG2JPG = convert
# JPGs will be resized to 600px width
SVG2JPG_FLAGS = -resize 600x -quality 100%
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf pdf text man changes linkcheck doctest gettext
@@ -46,17 +43,17 @@ help:
clean:
-rm -rf $(BUILDDIR)/*
-@rm -f $(JPGs)
-@rm -f $(PDFs)
# Pattern rule for converting SVG to JPG
%_svg.jpg : %.svg
$(SVG2JPG) $(SVG2JPG_FLAGS) $< $@
# Pattern rule for converting SVG to PDF
%.pdf : %.svg
inkscape -f $< -A $@
# Build a list of SVG files to convert to JPGs
JPGs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%_svg.jpg,$(wildcard $(dir)/*.svg)))
# Make a rule to build the JPGs
images: $(JPGs)
# Build a list of SVG files to convert to PDFs
PDFs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.pdf,$(wildcard $(dir)/*.svg)))
# Make a rule to build all images
images: $(PDFs)
all: clean html dirhtml singlehtml latexpdf pdf

12
README.md
View File

@@ -36,8 +36,9 @@ And Sphinx necessary extensions:
sudo pip install -r requirements.txt
In addition to these eggs you will need to install
[PlantUML](http://plantuml.sourceforge.net/ "PlantUML") and
[ImageMagick](http://www.imagemagick.org/ "ImageMagick").
[PlantUML](http://plantuml.sourceforge.net/ "PlantUML"),
[ImageMagick](http://www.imagemagick.org/ "ImageMagick"), and
[Inkscape](http://inkscape.org/ "Inkscape").
To install PlantUML you run this wget process:
@@ -48,9 +49,10 @@ To install PlantUML you run this wget process:
PlantumUML requires java:
sudo apt-get install openjdk-7-jre
To edit SVG images we use [Inkscape](http://inkscape.org/ "Inkscape") but
you may use any other SVG-capable tool you like. We're not picky.
We use [Inkscape](http://inkscape.org/ "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
========

856
_images/ha-overview-red-hat.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 48 KiB

4
pages/install-guide/0000-intro.rst
View File

@@ -90,4 +90,6 @@ clouds:
Fuel is designed to maintain the OpenStack environment while providing
the flexibility to adapt it to your configuration.
.. image:: /_images/how-it-works_svg.jpg
.. image:: /_images/how-it-works.*
:width: 80%
:align: center

3
pages/install-guide/0030-how-it-works.rst
View File

@@ -47,7 +47,8 @@ In practice, Fuel works as follows:
Fuel is designed to enable you to maintain your environment, while giving you
the flexibility to adapt it to your own business needs and scale.
.. image:: /_images/how-it-works_svg.jpg
.. image:: /_images/how-it-works.*
:width: 100%
:align: center
Fuel comes with several pre-defined deployment configurations, plus

8
pages/install-guide/networks.rst
View File

@@ -59,6 +59,7 @@ FlatDHCPManager (single-interface scheme)
-----------------------------------------
.. image:: /_images/flatdhcpmanager-sh_scheme.jpg
:width: 100%
:align: center
In order for FlatDHCPManager to work, one designated switch port where each
@@ -70,6 +71,10 @@ routed on the host machine according to the routing table. The default route
will point to the gateway specified on the networks tab in the UI as the
gateway for the Public network.
.. raw:: pdf
PageBreak
VLANManager
------------
@@ -82,6 +87,7 @@ traffic from VMs of other projects. Again, like with FlatDHCPManager, switch
ports must be configured as tagged (trunk) ports to allow this scheme to work.
.. image:: /_images/vlanmanager_scheme.jpg
:width: 100%
:align: center
.. raw:: pdf
@@ -104,7 +110,7 @@ Configuring the network
Once you choose a networking mode (FlatDHCP/VLAN), you must configure equipment
accordingly. The diagram below shows an example configuration.
.. image:: /_images/physical-network.jpg
.. image:: /_images/physical-network.png
:width: 100%
:align: center

3
pages/reference-architecture/0012-simple.rst
View File

@@ -15,7 +15,8 @@ of compromises as to the number and types of services that you can
deploy. It is, however, extremely useful if you just want to see how
OpenStack works from a user's point of view.
.. image:: /_images/deployment-simple_svg.jpg
.. image:: /_images/deployment-simple.*
:width: 60%
:align: center
More commonly, your OpenStack installation will consist of multiple

7
pages/reference-architecture/0014-compact.rst
View File

@@ -1,7 +1,3 @@
.. raw:: pdf
PageBreak
.. index:: Reference Architectures: Multi-node with HA
.. _Multi-node_HA:
@@ -17,7 +13,8 @@ single points of failure. That's not to say, however, that you can't
reduce hardware requirements by combining your storage, network, and controller
nodes:
.. image:: /_images/deployment-ha-compact_svg.jpg
.. image:: /_images/deployment-ha-compact.*
:width: 80%
:align: center
We'll take a closer look at the details of this deployment configuration in

14
pages/reference-architecture/0015-closer-look.rst
View File

@@ -1,7 +1,3 @@
.. raw:: pdf
PageBreak
.. index:: Reference Architectures: Multi-node with HA Details
.. _Close_look_Multi-node_HA:
@@ -9,13 +5,6 @@
Details of Multi-node with HA Deployment
========================================
In this section, you'll learn more about the Multi-node with HA
deployment configuration and how it achieves high availability. As you may
recall, this configuration looks something like this:
.. image:: /_images/deployment-ha-compact_svg.jpg
:align: center
OpenStack services are interconnected by RESTful HTTP-based APIs and
AMQP-based RPC messages. So redundancy for stateless OpenStack API
services is implemented through the combination of Virtual IP (VIP)
@@ -25,7 +14,8 @@ rely on their respective active/active and active/passive modes for high availab
For example, RabbitMQ uses built-in clustering capabilities, while the
database uses MySQL/Galera replication.
.. image:: /_images/ha-overview_svg.jpg
.. image:: /_images/ha-overview.*
:width: 100%
:align: center
Lets take a closer look at what an OpenStack deployment looks like, and

9
pages/reference-architecture/0018-red-hat-differences.rst
View File

@@ -48,7 +48,8 @@ of compromises as to the number and types of services that you can
deploy. It is, however, extremely useful if you just want to see how
OpenStack works from a user's point of view.
.. image:: /_images/deployment-simple_svg.jpg
.. image:: /_images/deployment-simple.*
:width: 60%
:align: center
More commonly, your OpenStack installation will consist of multiple
@@ -74,7 +75,8 @@ single points of failure. That's not to say, however, that you can't
reduce hardware requirements by combining your storage, network, and controller
nodes:
.. image:: /_images/deployment-ha-compact-red-hat_svg.jpg
.. image:: /_images/deployment-ha-compact-red-hat.*
:width: 80%
:align: center
OpenStack services are interconnected by RESTful HTTP-based APIs and AMQP-based
@@ -86,5 +88,6 @@ availability. For example, MySQL uses built-in replication capabilities (plus
the help of Pacemaker), while QPID is offered in three independent brokers with
virtual IP management to provide high availability.
.. image:: /_images/ha-overview-red-hat_svg.jpg
.. image:: /_images/ha-overview-red-hat.*
:width: 80%
:align: center

9
pages/reference-architecture/0020-logical-setup.rst
View File

@@ -21,7 +21,8 @@ You must keep in mind, however, that the database uses Galera to
achieve HA, and Galera is a quorum-based system. That means that you must provide
at least 3 controller nodes.
.. image:: /_images/logical-diagram-controller.svg
.. image:: /_images/logical-diagram-controller.*
:width: 80%
:align: center
Every OpenStack controller runs HAProxy, which manages a single External
@@ -63,7 +64,8 @@ as RabbitMQ and MySQL. They use the same approach that provides
redundancy to the end-users of Horizon and REST APIs, reaching out to
controller nodes using the VIP and going through HAProxy.
.. image:: /_images/logical-diagram-compute_svg.jpg
.. image:: /_images/logical-diagram-compute.*
:width: 80%
:align: center
Storage Nodes
@@ -76,5 +78,6 @@ achieve this, you are going to deploy Swift. This enables you to use
it not only for storing VM images, but also for any other objects such
as user files.
.. image:: /_images/logical-diagram-storage_svg.jpg
.. image:: /_images/logical-diagram-storage.*
:width: 80%
:align: center

6
pages/reference-architecture/0030-cluster-sizing.rst
View File

@@ -19,7 +19,8 @@ deployment is to allocate 4 nodes:
- 1 compute node
.. image:: /_images/deployment-ha-compact_svg.jpg
.. image:: /_images/deployment-ha-compact.*
:width: 80%
:align: center
If you want to run storage separately from the controllers, you can do that as
@@ -33,7 +34,8 @@ well by raising the bar to 9 nodes:
- 1 Compute node
.. image:: /_images/deployment-ha-full_svg.jpg
.. image:: /_images/deployment-ha-full.*
:width: 80%
:align: center
Of course, you are free to choose how to deploy OpenStack based on the

5
pages/reference-architecture/0040-network-setup.rst
View File

@@ -83,7 +83,6 @@ NIC cards. They're utilized as follows:
The figure below illustrates the relevant nodes and networks in Neutron VLAN mode.
.. image:: /_images/080-networking-diagram_svg.jpg
.. image:: /_images/080-networking-diagram.*
:width: 75%
:align: center

24
pages/reference-architecture/0060-quantum-vs-nova-network.rst
View File

@@ -94,18 +94,18 @@ like this:
The most likely configuration for different number NICs on cluster nodes:
+------+--------------------------------------------+--------------------------------------------+
| NICs | VLAN | GRE |
+======+============================================+============================================+
| 2 | Not supported | .. image:: /_images/q32_gre_2nic_svg.jpg |
| | | :align: center |
+------+--------------------------------------------+--------------------------------------------+
| 3 | .. image:: /_images/q32_vlan_3nic_svg.jpg | .. image:: /_images/q32_gre_3nic_svg.jpg |
| | :align: center | :align: center |
+------+--------------------------------------------+--------------------------------------------+
| 4 | .. image:: /_images/q32_vlan_4nic_svg.jpg | .. image:: /_images/q32_gre_4nic_svg.jpg |
| | :align: center | :align: center |
+------+--------------------------------------------+--------------------------------------------+
+------+--------------------------------------+--------------------------------------+
| NICs | VLAN | GRE |
+======+======================================+======================================+
| 2 | Not supported | .. image:: /_images/q32_gre_2nic.* |
| | | :align: center |
+------+--------------------------------------+--------------------------------------+
| 3 | .. image:: /_images/q32_vlan_3nic.* | .. image:: /_images/q32_gre_3nic.* |
| | :align: center | :align: center |
+------+--------------------------------------+--------------------------------------+
| 4 | .. image:: /_images/q32_vlan_4nic.* | .. image:: /_images/q32_gre_4nic.* |
| | :align: center | :align: center |
+------+--------------------------------------+--------------------------------------+
Known limitations