source: softGlue_examples/source/adding_examples.rst @ 923

Last change on this file since 923 was 923, checked in by jemian, 10 years ago

tweaked the instructions for publishing from the SVN server

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Revision Author HeadURL Id
File size: 4.1 KB
Line 
1.. $Id: adding_examples.rst 923 2012-06-13 17:11:59Z jemian $
2
3===========================================
4Adding new examples
5===========================================
6
7To :index:`!add new examples`, follow these steps:
8
9#. make a new subdirectory under ``source/``
10#. copy any image files into this new subdirectory
11#. copy ``programmable_pulse_train/index.rst`` 
12   into this new subdirectory
13#. edit the new ``index.rst`` file to show the
14   images and text for this new example
15#. edit ``source/index.rst`` and add a reference to
16   the new directory in the ``toctree`` under
17   ``programmable_pulse_train/index``
18#. in ``source``, add the new directory to subversion
19#. in ``source/..`` (parent directory), type ``make html`` 
20   to rebuild the web site
21#. it may be necessary to tell subversion the mime
22   type of the html file(s), see below
23#. in the same directory, do a subversion checkin: 
24   ``svn ci -m "new example"``
25
26setting the subversion mime type of a file
27++++++++++++++++++++++++++++++++++++++++++
28
29=========  ========================================
30extension  command
31=========  ========================================
32``.html``  ``svn ps svn:mime-type text/html``
33``.css``   ``svn ps svn:mime-type text/css``
34``.js``    ``svn ps svn:mime-type text/javascript``
35=========  ========================================
36
37Publishing new content as HTML
38++++++++++++++++++++++++++++++
39
40The subversion repository also can act as a WWW server.
41It is possible to publish the built HTML documentatiojn
42as a complete web site directly from the subversion server.
43For this to happen, the built documentation needs to be added
44to the subversion repository.  The MIME types of certain files
45needs to be set properly so the SVN server can deliver them
46identified in a way that WWW clients will render them properly.
47
48The commands below may be useful at times when adding
49new examples so the HTML files display properly from the
50subversion repository server::
51
52        cd {softGlue_examples}
53       
54        # these commands will add all built HTML content
55        svn add build/html/*
56        svn add build/html/*/*
57        # -or-  (to be more selective as to what is published)
58        svn st -u
59        svn add {any content from previous "svn st" command with "?" in left column}
60       
61        # Now, you need to set the MIME types properly
62        # or the SVN server will display the pages unformatted.
63        svn ps svn:mime-type text/html build/html/*.html
64        svn ps svn:mime-type text/html build/html/*/*.html
65        svn ps svn:mime-type text/javascript build/html/_static/*.js
66        svn ps svn:mime-type text/css build/html/_static/*.css
67
68Advisory about ``make clean``
69^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
70
71When a Sphinx web site is to be published from the SVN server,
72it is important to avoid the use of ``make clean``.  The *clean*
73procedure in the standard as-supplied Sphinx Makefile completely
74removes all content under the ``build/``
75subdirectory (including the ``build/html/.svn`` subdirectory)
76and removes the subversion information necessary to republish the WWW site.
77
78Instead of ``make clean``, you can force a complete Sphinx rebuild
79by removing the ``build/doctrees`` subdirectory.  Either edit
80the Makefile accordingly (as has been done here) or use this command::
81
82   /bin/rm -rf build/doctrees
83
84On this modified Makefile, ``make clean`` should look like this::
85
86  [jemian@gov,286,softGlue_examples]$ make clean
87  #-rm -rf build/*
88  rm -rf build/doctrees
89
90
91Restoring SVN ``build/html/.svn`` subdirectory
92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93
94If the ``build/html/.svn`` has been removed,
95it can be easy to restore from the SVN repository.
96Try these commands::
97
98   mv build build.modified
99   svn update
100   make html
101
102Once you are confident that things work the way they should,
103you can remove the old ``build.modified`` directory::
104
105   /bin/rm -rf build.modified
106
107.. note:: This can still retain unused content in the ``build/html``
108   subdirectory (only a problem for the few who browse the
109   ``build/html`` subdirectory contents). 
110   To completely rebuild the published web site), it
111   may be necessary to remove the ``build/html`` subdirectory from the
112   SVN repository, commit that change, rebuild the web site, then add
113   the new ``build/html`` subdirectory back into SVN.
Note: See TracBrowser for help on using the repository browser.