Adjusted rtd config to not use BlockDiag on the rtd server. Added a python script, kotti_blockdiag.py, to generate PNGs for diagrams, which are defined in .diag files. The .diag files are read from scripts/blockdiag/ and the images are saved to docs/images in the same way that kotti_capture.py works. Updated readme with new instructions.

Author: geojeff

README.rst

@@ -18,9 +18,23 @@ Make a virtualenv and prepare to use Kotti and selenium::
 
   pip install kotti_docs_theme
 
-  wget http://sourceforge.net/projects/dejavu/files/dejavu/2.33/dejavu-fonts-ttf-2.33.tar.bz2
+  pip install BlockDiag
 
-Run Kotti::
+PIL is already installed by Kotti requirements, and BlockDiag needs it. Check
+that you have freetype2 on your system and that the installation of PIL sees
+it.
+
+Visit http://dejavu-fonts.org/wiki/Download and download into the /scripts
+directory a set of fonts to use. We should probably try to use a given set.
+So far, the set used is::
+
+  wget http://sourceforge.net/projects/dejavu/files/dejavu/2.33/dejavu-fonts-ttf-2.33.tar.bz2 
+
+After exploding the fonts, you should have the ttf files in::
+
+  scripts/dejavu-fonts-ttf-2.33/ttf/
+
+Run Kotti from the kotti_user_manual virtualenv directory::
 
   pserve app.ini
 
@@ -41,23 +55,68 @@ http://code.google.com/p/chromedriver/downloads/list, then download the
 chromedriver to the scripts directory. You do not have to download a
 driver for using the Firefox webdriver.
 
-Then run the script::
+Then run the script from the kotti_user_manual/scripts/ directory::
 
   python kotti_capture.py
 
-This script saves images in the scripts/ directory, and stores a
-chromedriver.log locally.
+This script saves screen capture images made with Selenium in the docs/images/
+directory, and stores a chromedriver.log locally.
+
+Then run the script::
+
+  python kotti_blockdiag.py
+
+This script uses the BlockDiag python package to generate PNG images for use in
+the docs. It is possible to embed the BlockDiag diagram definitions in the rst
+docs as directives. However, so far at least, to take advantage of ttf fonts as
+this script does, we need to generate the PNG files on our own machines that
+have PIL installed with freetype2 installed.
 
-Using the Script
-----------------
+Working with the kotti_capture.py Script
+----------------------------------------
 
-In docs/ .rst files, add images as you normally would, according to Sphinx
-documentation. The entries will have the form ``.. Image::
-../images/add_menu.png``. The script reads the docs files, looking for such
-image entries, then calls the matching function, as with ``add_menu()``. 
+In docs/ .rst files, add images as you normally would for Sphinx, according to
+its documentation. The entries will have the form::
+
+  ``.. Image:: ../images/add_menu.png``
+  
+You need to add a matching function, e.g. add_menu(), which must be made
+through study of existing functions and experimentation. It is very much a
+system where success is found by trial and error, combining attempts in the
+Python code to use Selenium to find elements and do the screen captures with
+element inspection using Browser tools to find ids, class names, and other
+targets for Selenium.
 
 Write functions that are dedicated to producing a given image, using whatever
 steps are needed in python-selenium operations. It can be necessary to perform
 several find, text and key entry, and click operations to achieve the desired
 state before capturing the image. See existing functions for the pattern,
-paying attention to the passing and order of creation for the browser object.
+paying attention to the order of steps. Little things matter.
+
+Working with the kotti_blockdiag.py Script
+------------------------------------------
+
+Add image directives for diagrams in the same way as you would for screen
+captures, e.g. a diagram PNG image might be::
+
+  ``.. Image:: ../images/anonymous_vs_authenticated.png``
+
+Add a corresponding BlockDiag diagram definition in scripts/blockdiag, e.g.
+
+  scripts/blockdiag/anonymous_vs_authenticated.diag
+
+See existing examples and the BlockDiag docs, and experiment. 
+
+Overall Routine
+---------------
+
+* Change / Run kotti_capture.py when something about Kotti changes, and fresh
+  screen captures are needed, or when something is added or removed.
+* Likewise, run kotti_blockdiag.py as needed when existing diagrams are
+  modified or new ones added.
+* Update docs files as needed for image directives from either kotti_capture.py
+  or kotti_blockdiag.py.
+* Update text of docs as needed.
+* Rerun docs/make html.
+* Push to github.com/Kotti/kotti_user_manual.
+* Log in to readthedocs.org and manually click the Build button.

docs/DejaVuSerif.ttf

@@ -253,11 +253,3 @@
     'mailing_list_url': 'http://groups.google.com/group/kotti',
     'irc_channel_url': 'irc://irc.freenode.net/#kotti',
 }
-
-# Enabled extensions
-extensions = ['sphinxcontrib.blockdiag']
-
-# Fontpath for blockdiag (truetype font)
-blockdiag_fontpath = os.path.join(os.path.abspath('.'), 'DejaVuSerif.ttf')
-
-blockdiag_antialias = True

docs/conf.py

@@ -71,7 +71,7 @@ Searching
     searching/searching
 
 Publishing
----------
+----------
 
 .. toctree::
     :maxdepth: 2

docs/images/anonymous_vs_authenticated.png

@@ -45,4 +45,6 @@ Document content type is the most important part of this concept. Documents are
 added to a Kotti website in the way word-processor documents are created, but
 in the context of the web. Documents contain text and may include images,
 files, and links to other documents.  Kotti's design makes linking documents to
-one another easy.
+one another happen automatically as the site structure is built. Plus, there
+are easy tools to make custom links between content items, or to other
+websites. 

docs/images/manufacturer_workflow.png

@@ -15,6 +15,8 @@ typical website, and private, for restricting viewing to the "logged in" user.
 Once a user has logged in, they can be called an ``authenticated`` user,
 because they have given their correct username and password.
 
+.. Image:: ../images/anonymous_vs_authenticated.png
+
 In its simplest form, Kotti allows a special user, called the Admin user, to
 log in and add and edit content. If the Kotti website is so simple that only
 one person will be adding content, that user will be the Admin user. The Admin
@@ -40,37 +42,7 @@ then emails her about the new account and her responsibilities.  Judy and
 Xavier will both have rights to add and edit content in the Legal Affairs
 section. Joe, Sally, Xavier, and Judy share responsibilities like this:
 
-.. blockdiag::
-
-    blockdiag {
-      Joe -- Sally -- Xavier;
-
-      // set default shape
-      default_shape = roundedbox;  // default value is 'box'
-
-      // set default colors
-      default_node_color = lightblue;
-      default_group_color = "#C0C0C0";
-      default_linecolor = "#808080";
-
-      group {
-        orientation = portrait;
-        label = 'Prospects';
-        Joe;
-      }
-
-      group {
-        orientation = portrait;
-        label = 'Existing Clients';
-        Sally;
-      }
-
-      group {
-        orientation = portrait;
-        label = 'Legal Affairs';
-        Xavier -- Judy;
-      }
-    }
+.. Image:: ../images/roles_music_agency.png
 
 Kotti includes a user registration system that can be open for general users to
 sign up. This is useful for social media websites that seek out membership. It
@@ -85,9 +57,11 @@ that organization. Rights can be assigned so that users in one group are
 restricted in what they can view, what they can add and edit. In the classic
 example, a newspaper could have user groups for reporters, photographers,
 editors, managers, etc. Each would have specific responsibilities and rights.
-A reporter can only write and compile articles, together with photographers. An
-editor can edit their work, but is not allowed to publish.  Only managers can
-publish content.
+A reporter can only write and compile articles, along with photographers.
+Together they could belong to a "Creators" group. An editor can edit their
+work, but is not allowed to publish.  Only managers can publish content.
+
+.. Image:: ../images/newspaper_workflow.png
 
 Even a small business with a handful of employees, or a small non-profit with
 just a few members, can benefit from some form of structure like this. Kotti

docs/images/newspaper_workflow.png

@@ -1,15 +1,47 @@
 Workflow Policies
 =================
 
-The term used for the setup for user and roles is ``workflow``. A workflow is a
-set of policies created for a given CMS setup, wherein user groups and roles
-are defined, and relationships and responsibilities are set.  Additional
-states, augmenting the default Public and Private, such as Pending, Postponed,
-Scheduled, Ready-For-Circulation, Needs-Full-Review, etc., may be added,
-depending on specific needs. As these state names suggest, this is an area
-where creativity can help to build a fine-grained system.
-
-You do not need to create a workflow policy to use a Kotti website. As user
-groups are created manually by the Admin user, a defacto workflow is created.
-A saved workflow is only created when there is a need to reuse a given set of
-policies.
+The term used for the setup for user and roles and related functionality is
+``workflow``.  You do not need to create a workflow policy to use a Kotti
+website. If you are the sole user of the website, then you can set up your own
+system, but when multiple people are involved, at least roles can be useful.
+But even then, a custom workflow is not needed, because as user groups are
+created by the Admin user, a simple defacto workflow is created using the
+built-in states, Private and Public. So, read about workflow for general
+interest, and for at least knowing the potential of workflows, should a need
+arise.
+
+A custom workflow is needed when there is more involved in the process of
+creating and editing content items in a succession.
+
+A workflow is constituted by a set of policies created for a given CMS setup,
+wherein user groups and roles are defined, and relationships and
+responsibilities established by creation of workflow states that expand upon
+Private and Public. These could include Pending, Postponed, Scheduled,
+Ready-For-Circulation, Needs-Full-Review, etc., depending on specific needs. As
+these state names suggest, this is an area where creativity can help to build a
+fine-grained system.
+
+For example, a manufacturing operation, e.g. for custom clothing, could have an
+in-house Kotti CMS for documenting and controlling flow of project work. The
+designers of the workflow would need to understand the physical layout and work
+schedules and constraints. They would create user roles for different stages of
+manufacture and assembly work, and custom content types with web forms that
+people would use to enter data into computer terminals on the work floor. A
+sequential flow of work stages would develop, starting with the initial work on
+the project piece, followed by quality control checks before it moves to the
+next workstation area. A given workstation could check a list of project pieces
+and where they are in the queue. The names of the workflow states and
+transitions might look like this:
+
+.. Image:: ../images/manufacturer_workflow.png
+
+Think of documents tied to individual project pieces by serial number, that
+would be marked as the items are carried through the process.
+
+For a similar example, Kotti could be used for a video production shop, which
+might have roles in the workflow such as "Ingestion," which would have people
+working with raw video in the first processing steps, along with roles for
+"Color Correcting," "Titles," "Special Effects," etc. And the states used along
+the way could include "Raw footage," "Initial Compression Good,", "Initial
+Compression Failed," "Color Corrected," "Ending Credits Added," etc. 

docs/images/roles_music_agency.png

@@ -1,6 +1,4 @@
 Sphinx
-hg+https://bitbucket.org/Surgo/blockdiag
-sphinxcontrib-blockdiag==1.1.1
 kotti_docs_theme
 repoze.sphinx.autointerface
 repoze.lru

docs/index.rst

@@ -0,0 +1,15 @@
+blockdiag {
+  orientation = landscape;
+
+  default_shape = roundedbox;
+  default_node_color = lightblue;
+  default_group_color = "#C0C0C0";
+  default_linecolor = "#808080";
+
+  Anonymous -> Authenticated [label="Log In", thick=3, color=black, fontsize=12, fontfamily='sansserif-normal'];
+
+  Anonymous [fontsize=14, fontfamily='sansserif-normal'];
+  Authenticated [fontsize=14, fontfamily='sansserif-normal'];
+
+}
+

docs/introduction/overview.rst

@@ -0,0 +1,23 @@
+blockdiag {
+  orientation = landscape;
+
+  default_shape = roundedbox;
+  default_node_color = lightblue;
+  default_group_color = "#C0C0C0";
+  default_linecolor = "#808080";
+  
+  node_width = 170;  // default value is 128
+  node_height = 100;  // default value is 40
+
+  span_width = 140;  // default value is 64
+  span_height = 120;  // default value is 40
+
+  Workstation-1 -> Workstation-2 [label="1-A-OK\n1-Has-Flaw-Fix\n1-Has-Flaw-Cull", thick=3, color=black, fontsize=12, fontfamily='sansserif-normal'];
+  Workstation-2 -> Workstation-3 [label="2-A-OK\n2-Has-Flaw-Fix\n2-Has-Flaw-Cull", thick=3, color=black, fontsize=12, fontfamily='sansserif-normal'];
+
+  Workstation-1 [fontsize=14, fontfamily='sansserif-normal'];
+  Workstation-2 [fontsize=14, fontfamily='sansserif-normal'];
+  Workstation-3 [fontsize=14, fontfamily='sansserif-normal'];
+
+}
+

docs/introduction/users_and_roles.rst

@@ -0,0 +1,51 @@
+blockdiag {
+  orientation = landscape;
+
+  default_shape = roundedbox;
+  default_node_color = lightblue;
+  default_group_color = "#C0C0C0";
+  default_linecolor = "#808080";
+
+  Reporter [fontsize=14, fontfamily='sansserif-normal'];
+  Photographer [fontsize=14, fontfamily='sansserif-normal'];
+  Cartoonist [fontsize=14, fontfamily='sansserif-normal'];
+  Statistician [fontsize=14, fontfamily='sansserif-normal'];
+  Artist [fontsize=14, fontfamily='sansserif-normal'];
+
+  Editor [fontsize=14, fontfamily='sansserif-normal'];
+  Manager [fontsize=14, fontfamily='sansserif-normal'];
+  Newspaper [shape=box, fontsize=14, fontfamily='sansserif-normal'];
+
+  Reporter -> Editor [label="Submit", thick=3, color=black, fontsize=12, fontfamily='sansserif-normal'];
+  Editor -> Manager [label="Submit", thick=3, color=black, fontsize=12, fontfamily='sansserif-normal'];
+  Manager -> Newspaper [label="Publish", thick=3, color=black, fontsize=12, fontfamily='sansserif-normal'];
+
+  group {
+    orientation = portrait;
+    label = 'Creators';
+    fontsize = 14;
+    fontfamily = 'sansserif-bold';
+    color = 'none';
+
+    Reporter -- Photographer -- Cartoonist -- Statistician -- Artist;
+  }
+
+  group {
+    label = 'Editors';
+    fontsize = 14;
+    fontfamily = 'sansserif-bold';
+    color = 'none';
+
+    Editor;
+  }
+
+  group {
+    label = 'Managers';
+    fontsize = 14;
+    fontfamily = 'sansserif-bold';
+    color = 'none';
+
+    Manager;
+  }
+
+}

docs/introduction/workflow.rst

@@ -0,0 +1,43 @@
+blockdiag {
+  orientation = landscape;
+
+  default_shape = roundedbox;
+  default_node_color = lightblue;
+  default_group_color = "#C0C0C0";
+  default_linecolor = "#808080";
+
+  Joe -- Sally -- Xavier;
+
+  Joe [fontsize=14, fontfamily='sansserif-normal'];
+  Sally [fontsize=14, fontfamily='sansserif-normal'];
+  Xavier [fontsize=14, fontfamily='sansserif-normal'];
+  Judy [fontsize=14, fontfamily='sansserif-normal'];
+
+  group {
+    label = 'Prospects';
+    fontsize = 14;
+    fontfamily = 'sansserif-bold';
+    color = 'none';
+
+    Joe;
+  }
+
+  group {
+    label = 'Existing Clients';
+    fontsize = 14;
+    fontfamily = 'sansserif-bold';
+    color = 'none';
+
+    Sally;
+  }
+
+  group {
+    orientation = portrait;
+    label = 'Legal Affairs';
+    fontsize = 14;
+    fontfamily = 'sansserif-bold';
+    color = 'none';
+
+    Xavier -- Judy;
+  }
+}