AETHER-2011 (part1)
Add basic 1.5 release documentation framework
Update edge deployment docs
- Describe different topologies and add deployment diagrams
- Split out Pronto BOM and diagrams
- Make BESS diagram a SVG
Updates to Sphinx and modules, fixed linkcheck to have a timeout/retry
for faulty webservers.
Fix spelling and formatting issue across entire site, remove "Smart
quotes" that cause the spellchecker to throw errors. Add many more
dictionary entries. Make spelling fail the build. Fix all spelling and
grammar errors that triggered failures.
Add autosectionlabel, and manage duplicate section names where they
existed.
Updated readme on image/diagram embedding
Added docs on PoE power cycle with Aruba switches (Pronto)
Change-Id: I7f9f7afae13788f9fe29bfe2683a295ba7b8914e
diff --git a/readme.rst b/readme.rst
index d77f726..289570e 100644
--- a/readme.rst
+++ b/readme.rst
@@ -53,26 +53,28 @@
<https://github.com/Holzhaus/sphinx-multiversion>`_ to build multiple versions
for the site.
-Creating Graphs and Diagrams
-----------------------------
+Adding Images and Diagrams
+--------------------------
-Multiple tools are available to render inline text-based graphs definitions and
-diagrams within the documentation. This is preferred over images as it's easier
-to change and see changes over time as a diff.
+There are multiple ways to add images and diagrams to the documentation.
+Generally, you should prefer using `SVG
+<https://en.wikipedia.org/wiki/Scalable_Vector_Graphics>`_ images, as these can
+be scaled to any size without quality loss.
-:doc:`Graphviz <sphinx:usage/extensions/graphviz>` supports many standard graph
-types.
+If you're creating diagrams, there are multiple tools available.
+:doc:`Graphviz <sphinx:usage/extensions/graphviz>` can render inline text-based
+graphs definitions and diagrams within the documentation, and is best for
+simple diagrams.
-The `blockdiag <http://blockdiag.com/en/blockdiag/sphinxcontrib.html>`_,
-`nwdiag, and rackdiag <http://blockdiag.com/en/nwdiag/sphinxcontrib.html>`_,
-and `seqdiag <http://blockdiag.com/en/seqdiag/sphinxcontrib.html>`_ suites of
-tools can be used to create specific types of diagrams:
+More complex diagrams can be created in `Diagrams.net/Draw.io
+<https://www.diagrams.net/>`_ format. When saving these diagrams, use the
+SVG format, and check the "Include a copy of my diagram". This will let
+someone open the SVG later directly from the documentation and edit it, without
+any loss in functionality or quality.
-- `blockdiag examples <http://blockdiag.com/en/blockdiag/examples.html>`_
-- `nwdiag examples <http://blockdiag.com/en/nwdiag/nwdiag-examples.html>`_
-- `rackdiag examples <http://blockdiag.com/en/nwdiag/rackdiag-examples.html>`_
-- `seqdiag examples <http://blockdiag.com/en/seqdiag/examples.html>`_
-
-The styles applied to nodes and connections in these diagrams can be customized
-using `attributes
-<http://blockdiag.com/en/blockdiag/attributes/node.attributes.html>`_.
+The last resort is to use raster images. If they're drawings or screen
+captures, use the `PNG
+<https://en.wikipedia.org/wiki/Portable_Network_Graphics>`_ format. Consider
+compressing them with a tool like `OptiPNG <http://optipng.sourceforge.net/>`_,
+or `pngquant <https://pngquant.org/>`_. If it's a photograph, use `JPEG
+<https://en.wikipedia.org/wiki/JPEG>`_.