source: softGlue_examples/source/adding_examples.rst @ 923

.. $Id: adding_examples.rst 923 2012-06-13 17:11:59Z jemian $

===========================================
Adding new examples
===========================================

To :index:`!add new examples`, follow these steps:

#. make a new subdirectory under ``source/``
#. copy any image files into this new subdirectory
#. copy ``programmable_pulse_train/index.rst`` 
   into this new subdirectory
#. edit the new ``index.rst`` file to show the 
   images and text for this new example
#. edit ``source/index.rst`` and add a reference to 
   the new directory in the ``toctree`` under 
   ``programmable_pulse_train/index``
#. in ``source``, add the new directory to subversion
#. in ``source/..`` (parent directory), type ``make html`` 
   to rebuild the web site
#. it may be necessary to tell subversion the mime 
   type of the html file(s), see below
#. in the same directory, do a subversion checkin:  
   ``svn ci -m "new example"``

setting the subversion mime type of a file
++++++++++++++++++++++++++++++++++++++++++

=========  ========================================
extension  command
=========  ========================================
``.html``  ``svn ps svn:mime-type text/html``
``.css``   ``svn ps svn:mime-type text/css``
``.js``    ``svn ps svn:mime-type text/javascript``
=========  ========================================

Publishing new content as HTML
++++++++++++++++++++++++++++++

The subversion repository also can act as a WWW server.
It is possible to publish the built HTML documentatiojn
as a complete web site directly from the subversion server.
For this to happen, the built documentation needs to be added
to the subversion repository.  The MIME types of certain files
needs to be set properly so the SVN server can deliver them
identified in a way that WWW clients will render them properly.

The commands below may be useful at times when adding 
new examples so the HTML files display properly from the
subversion repository server::

        cd {softGlue_examples}
        
        # these commands will add all built HTML content
        svn add build/html/*
        svn add build/html/*/*
        # -or-  (to be more selective as to what is published)
        svn st -u
        svn add {any content from previous "svn st" command with "?" in left column}
        
        # Now, you need to set the MIME types properly
        # or the SVN server will display the pages unformatted.
        svn ps svn:mime-type text/html build/html/*.html
        svn ps svn:mime-type text/html build/html/*/*.html
        svn ps svn:mime-type text/javascript build/html/_static/*.js
        svn ps svn:mime-type text/css build/html/_static/*.css

Advisory about ``make clean``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When a Sphinx web site is to be published from the SVN server,
it is important to avoid the use of ``make clean``.  The *clean*
procedure in the standard as-supplied Sphinx Makefile completely 
removes all content under the ``build/``
subdirectory (including the ``build/html/.svn`` subdirectory)
and removes the subversion information necessary to republish the WWW site.

Instead of ``make clean``, you can force a complete Sphinx rebuild
by removing the ``build/doctrees`` subdirectory.  Either edit 
the Makefile accordingly (as has been done here) or use this command::

   /bin/rm -rf build/doctrees

On this modified Makefile, ``make clean`` should look like this::

  [jemian@gov,286,softGlue_examples]$ make clean
  #-rm -rf build/*
  rm -rf build/doctrees


Restoring SVN ``build/html/.svn`` subdirectory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the ``build/html/.svn`` has been removed, 
it can be easy to restore from the SVN repository.
Try these commands::

   mv build build.modified
   svn update
   make html

Once you are confident that things work the way they should,
you can remove the old ``build.modified`` directory::

   /bin/rm -rf build.modified

.. note:: This can still retain unused content in the ``build/html``
   subdirectory (only a problem for the few who browse the
   ``build/html`` subdirectory contents).  
   To completely rebuild the published web site), it
   may be necessary to remove the ``build/html`` subdirectory from the
   SVN repository, commit that change, rebuild the web site, then add
   the new ``build/html`` subdirectory back into SVN.