docs: add doc from sphinxconrib-aafig, restructure chapters

- use parts of sphinxconrib-aafig' README in sphinx.rst - put all integrations (docutils, sphinx, moin) into separate chapter and files - cleanup manual - update credits
aafigure · May 9, 2017 · 967778c · 967778c
1 parent 6ba8bf3
commit 967778c
Show file tree

Hide file tree

Showing 9 changed files with 270 additions and 204 deletions.
diff --git a/CREDITS.rst b/CREDITS.rst
@@ -2,9 +2,9 @@
  Credits
 =========
 
-- Chris Liechti (zsquareplusc)
-- Leandro Lucarella (llucax)
-- Oliver Joos
+- Chris Liechti (zsquareplusc) - creator
+- Leandro Lucarella (llucax) - contributor, sphinxcontrib-aafig
+- Oliver Joos - contributor
 - Jim Wisniewski
 - Florent Gallaire
 - ... not all names may be listed here, see also ``git log`` or online history_

diff --git a/aafigure/sphinxext.py b/aafigure/sphinxext.py
@@ -17,20 +17,20 @@
 ## legal stuff just for a simple piece of software I don't really mind anyone
 ## using. But I also believe that it's important that people share and give back;
 ## so I'm placing this work under the following license.
-## 
-## 
+##
+##
 ## BOLA - Buena Onda License Agreement (v1.0)
 ## ------------------------------------------
-## 
+##
 ## This work is provided 'as-is', without any express or implied warranty. In no
 ## event will the authors be held liable for any damages arising from the use of
 ## this work.
-## 
+##
 ## To all effects and purposes, this work is to be considered Public Domain.
-## 
-## 
+##
+##
 ## However, if you want to be "buena onda", you should:
-## 
+##
 ## 1. Not take credit for it, and give proper recognition to the authors.
 ## 2. Share your modifications, so everybody benefits from them.
 ## 3. Do something nice for the authors.

diff --git a/documentation/docutils.rst b/documentation/docutils.rst
@@ -0,0 +1,56 @@
+==========
+ Docutils
+==========
+
+The docutils directive is provided in `aafigure/docutils`.
+
+
+Docutils directive
+==================
+The ``aafigure`` directive has the following options:
+
+- ``:scale: <float>``   enlarge or shrink image
+
+- ``:line_width: <float>``   change line with (svg only currently)
+
+- ``:format: <str>`` choose backend/output format: 'svg', 'png', all
+  bitmap formats that PIL supports can be used but only few make sense. Line
+  drawings have a good compression and better quality when saved as PNG
+  rather than a JPEG. The best quality will be achieved with SVG, tough not
+  all browsers support this vector image format at this time.
+
+- ``:foreground: <str>``   foreground color in the form ``#rgb`` or ``#rrggbb``
+
+- ``:background: <str>``   background color in the form ``#rgb`` or ``#rrggbb``
+  (*not* for SVG output)
+
+- ``:fill: <str>``   fill color in the form ``#rgb`` or ``#rrggbb``
+
+- ``:name: <str>``   use this as filename instead of the automatic generated
+  name
+
+- ``:aspect: <float>``  change aspect ratio. Effectively it is the width of the
+  image that is multiplied by this factor. The default setting ``1`` is useful
+  when shapes must have the same look when drawn horizontally or vertically.
+  However, ``:aspect: 0.5`` looks more like the original ASCII and even smaller
+  factors may be useful for timing diagrams and such. But there is a risk that
+  text is cropped or is draw over an object beside it.
+
+  The stretching is done before drawing arrows or circles, so that they are
+  still good looking.
+
+- ``:proportional: <flag>``  use a proportional font instead of a mono-spaced
+  one.
+
+Docutils plug-in
+================
+The docutils-aafigure_ extension depends on the aafigure package also requires
+``setuptools`` (often packaged as ``python-setuptools``) and Docutils_ itself
+(0.5 or newer) must be installed.
+
+After that, the ``aafigure`` directive will be available.
+
+.. _docutils-aafigure: http://pypi.python.org/pypi/aafigure
+.. _Docutils: http://docutils.sf.net
+
+
diff --git a/documentation/index.rst b/documentation/index.rst
@@ -12,6 +12,7 @@ aafigure Documentation
     manual
     shortintro
     examples
+    integrations
     appendix
 
 Indices and tables

diff --git a/documentation/integrations.rst b/documentation/integrations.rst
@@ -0,0 +1,11 @@
+==============
+ Integrations
+==============
+
+.. toctree::
+    :maxdepth: 2
+
+    sphinxext
+    docutils
+    moinmoin
+
diff --git a/documentation/manual.rst b/documentation/manual.rst
@@ -68,81 +68,25 @@ Installation
 
 aafigure
 --------
+::
+
+    pip install aafigure
+
 This installs a package that can be used from python (``import aafigure``) and
 a command line script called ``aafigure``.
 
 The Python Imaging Library (PIL) needs to be installed when support for bitmap
 formats is desired and it will need ReportLab for PDF output.
 
-To install the module for all users on the system, administrator rights (root)
-is required..
-
-From source (tar.gz or checkout)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Unpack the archive, enter the ``aafigure-x.y`` directory and run::
-
-    python setup.py install
-
-Setuptools/PyPI
-~~~~~~~~~~~~~~~
-Alternatively it can be installed from PyPy, either manually downloading the
-files and installing as described above or using::
-
-    easy_install -U aafigure
-
-Packages
-~~~~~~~~
-There are also packaged versions for some Linux distributions and Windows:
-
-Ubuntu
-    Add the repository to ``/etc/apt/sources.list`` as described on this page:
-    https://launchpad.net/~aafigure-team/+archive/ppa
-
-    Then run ``apt-get update`` and ``apt-get install aafigure``
-
-Arch Linux
-    "aafigure" (or "aafigure-bzr") are found in the category "unsupported".
-
-Windows
-    For users that have Python already installed, there is an installer for
-    the extension on http://pypi.python.org/pypi/aafigure
-
-
-Docutils plug-in
-----------------
-The docutils-aafigure_ extension depends on the aafigure package also requires
-``setuptools`` (often packaged as ``python-setuptools``) and Docutils_ itself
-(0.5 or newer) must be installed.
-
-After that, the ``aafigure`` directive will be available.
-
-.. _docutils-aafigure: http://pypi.python.org/pypi/aafigure
-.. _Docutils: http://docutils.sf.net
-
-
-Sphinx plug-in
---------------
-sphinxcontrib-aafig_ is a plug-in similar to the Docutils_ plug-in, but it
-automatically selects the image format depending on the output format.
-
-.. _sphinxcontrib-aafig: http://pypi.python.org/pypi/sphinxcontrib-aafig
-
-
-MoinMoin plug-in
-----------------
-MoinMoin_ is a popular Wiki engine. The plug-in allows to use aafigure drawings
-within wiki pages.
+Requirements
+~~~~~~~~~~~~
 
-Copy the file ``aafig.py`` from ``examples/moinmoin`` to
-``wiki/data/plugin/parser`` of the wiki. The aafigure module itself needs to
-be installed for the Python version that is used to run MoinMoin_ (see above for
-instructions).
+* reportlab_ (for LaTeX/PDF output)
+* PIL_ or Pillow_ (for any image format other than SVG or PDF)
 
-Tested with MoinMoin 1.8.
-
-See also: http://moinmo.in/ParserMarket/AaFigure
-
-.. _MoinMoin: http://moinmo.in
+.. _reportlab: http://www.reportlab.org/
+.. _PIL: http://www.pythonware.com/products/pil/
+.. _Pillow: https://python-pillow.org/
 
 
 Usage
@@ -158,67 +102,3 @@ at the command's help (or man page)::
 
     aafigure --help
 
-Within Docutils
----------------
-A ``aafigure`` directive is provided that allows to insert images::
-
-    .. aafigure::
-
-        DD o--->
-
-::
-
-    ./rst2html.py README.txt >README.html
-
-This results in the ``README.html`` file and a ``.svg`` file (or the specified
-file type) for each ``aafigure``.
-
-The resulting ``README.html`` file can be viewed with a SVG capable browser. It
-has been tested with Firefox 1.5, 2.0 and 3.0.
-
-Within Sphinx
--------------
-In ``conf.py`` add::
-
-    extensions = ['sphinxcontrib.aafig']
-
-This provides the ``aafig`` directive::
-
-    .. aafig::
-
-        DD o--->
-
-The output format is automatically chosen depending on the generated document
-format (e.g. HTML or PDF).
-
-Within MoinMoin
----------------
-ASCII Art figures can be inserted into a MoinMoin_ WikiText page the following
-way::
-
-    {{{#!aafig scale=1.5 foreground=#ff1010
-    DD o--->
-    }}}
-
-The parser name is ``aafig`` and options are appended, separated with spaces.
-Options that require a value take that after a ``=`` without any whitespace
-between option and value.  Supported options are:
-
-    - ``scale=<float>``
-    - ``aspect=<float>``
-    - ``textual``
-    - ``textual_strict``
-    - ``proportional``
-    - ``linewidth=<float>``
-    - ``foreground=#rrggbb``
-    - ``fill=#rrggbb``
-
-There is no ``background`` as the SVG backend ignores that. And it is not possible
-to pass generic options.
-
-The images are generated and stored in MoinMoin's internal cache. So there is
-no mess with attached files on the page. Each change on an image generates a
-new cache entry so the cache may grow over time. However the files can be
-deleted with no problem as they can be rebuilt when the page is viewed again
-(the old files are not automatically deleted as they are still used when older
-revision of a page is displayed).
diff --git a/documentation/moinmoin.rst b/documentation/moinmoin.rst
@@ -0,0 +1,48 @@
+==================
+ MoinMoin plug-in
+==================
+MoinMoin_ is a popular Wiki engine. The plug-in allows to use aafigure drawings
+within wiki pages.
+
+Copy the file ``aafig.py`` from ``examples/moinmoin`` to
+``wiki/data/plugin/parser`` of the wiki. The aafigure module itself needs to
+be installed for the Python version that is used to run MoinMoin_ (see above for
+instructions).
+
+Tested with MoinMoin 1.8.
+
+See also: http://moinmo.in/ParserMarket/AaFigure
+
+.. _MoinMoin: http://moinmo.in
+
+Usage
+=====
+ASCII Art figures can be inserted into a MoinMoin_ WikiText page the following
+way::
+
+    {{{#!aafig scale=1.5 foreground=#ff1010
+    DD o--->
+    }}}
+
+The parser name is ``aafig`` and options are appended, separated with spaces.
+Options that require a value take that after a ``=`` without any whitespace
+between option and value.  Supported options are:
+
+    - ``scale=<float>``
+    - ``aspect=<float>``
+    - ``textual``
+    - ``textual_strict``
+    - ``proportional``
+    - ``linewidth=<float>``
+    - ``foreground=#rrggbb``
+    - ``fill=#rrggbb``
+
+There is no ``background`` as the SVG backend ignores that. And it is not possible
+to pass generic options.
+
+The images are generated and stored in MoinMoin's internal cache. So there is
+no mess with attached files on the page. Each change on an image generates a
+new cache entry so the cache may grow over time. However the files can be
+deleted with no problem as they can be rebuilt when the page is viewed again
+(the old files are not automatically deleted as they are still used when older
+revision of a page is displayed).
diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst
@@ -2,69 +2,6 @@
  Short introduction
 ====================
 
-Docutils & Sphinx integration
-=============================
-
-In a Sphinx document an image can be inserted like this::
-
-    .. aafig::
-
-        -->
-
-Which results in an image like this:
-
-.. aafig::
-
-    -->
-
-The same contents could also have been placed in a file and then be converted
-with the aafigure command line tool.
-
-Docutils directive
-------------------
-The ``aafigure`` directive has the following options:
-
-- ``:scale: <float>``   enlarge or shrink image
-
-- ``:line_width: <float>``   change line with (svg only currently)
-
-- ``:format: <str>`` choose backend/output format: 'svg', 'png', all
-  bitmap formats that PIL supports can be used but only few make sense. Line
-  drawings have a good compression and better quality when saved as PNG
-  rather than a JPEG. The best quality will be achieved with SVG, tough not
-  all browsers support this vector image format at this time.
-
-- ``:foreground: <str>``   foreground color in the form ``#rgb`` or ``#rrggbb``
-
-- ``:background: <str>``   background color in the form ``#rgb`` or ``#rrggbb``
-  (*not* for SVG output)
-
-- ``:fill: <str>``   fill color in the form ``#rgb`` or ``#rrggbb``
-
-- ``:name: <str>``   use this as filename instead of the automatic generated
-  name
-
-- ``:aspect: <float>``  change aspect ratio. Effectively it is the width of the
-  image that is multiplied by this factor. The default setting ``1`` is useful
-  when shapes must have the same look when drawn horizontally or vertically.
-  However, ``:aspect: 0.5`` looks more like the original ASCII and even smaller
-  factors may be useful for timing diagrams and such. But there is a risk that
-  text is cropped or is draw over an object beside it.
-
-  The stretching is done before drawing arrows or circles, so that they are
-  still good looking.
-
-- ``:proportional: <flag>``  use a proportional font instead of a mono-spaced
-  one.
-
-
-Sphinx directive
-----------------
-It is called ``aafig``. The same options as for the Docutils directive apply
-with the exception of ``format``. That option is not supported as the format
-is automatically determined.
-
-
 Lines
 =====
 The ``-`` and ``|`` are normally used for lines. ``_`` and ``~`` can also be