From 48b2f3dd2f166f261b03288ae10bf60abbfc05f1 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 13 May 2010 06:06:22 -0400 Subject: [PATCH] Documentation cleanups. Specifically: * Escape *nix -> \*nix, because the bare * looks like an emphasis start mark. * Use :file:`...` to denote files. * Fix FHS reference '_ ..' -> '.. _' * Add a link to Sphinx's markup extensions. * Remove superfluous "Hooke" from section titles. * Use correct section linking: X.txt -> X :doc:`X` see http://sphinx.pocoo.org/concepts.html#document-names http://sphinx.pocoo.org/markup/inline.html#role-doc * Use two spaces (not one) at start of sentences. * `code` -> ``code`` (the way I had things originally :p). See http://sphinx.pocoo.org/markup/inline.html#role-samp --- doc/config.txt | 11 +++-- doc/doc.txt | 4 +- doc/hacking.txt | 11 ++--- doc/index.txt | 22 ++++----- doc/testing.txt | 20 ++++---- doc/tutorial.txt | 124 ++++++++++++++++++++++------------------------- 6 files changed, 93 insertions(+), 99 deletions(-) diff --git a/doc/config.txt b/doc/config.txt index c5d594f..d2b8d14 100644 --- a/doc/config.txt +++ b/doc/config.txt @@ -31,14 +31,15 @@ Finding configuration files --------------------------- The default search path follows the `Filesystem Hierarchy Standard`_, -and so will probably need adjustment for non-*nix systems. The +and so will probably need adjustment for non-\*nix systems. The default path list is -* /usr/share/hooke/hooke.cfg -* /etc/hooke/hooke.cfg -* ~/.hooke.cfg +* :file:`/usr/share/hooke/hooke.cfg` +* :file:`/etc/hooke/hooke.cfg` +* :file:`~/.hooke.cfg` +* :file:`./.hooke.cfg` but alternatives can be specified from the command line launching Hooke. -_ ..Filesystem Hierarchy Standard: http://www.pathname.com/fhs/ +.. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs/ diff --git a/doc/doc.txt b/doc/doc.txt index b81c2ff..4c8b41f 100644 --- a/doc/doc.txt +++ b/doc/doc.txt @@ -20,9 +20,11 @@ For which you'll need to install Sphinx, numpydoc, and SCons_:: See the reStructuredText quick reference and the `NumPy/SciPy documentation guide`_ for an introduction to the documentation -syntax. +syntax. See the `Sphinx markup documentation`_ for a discussion +of Sphinx's reStructuredText extensions. .. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html .. _NumPy/SciPy documentation guide: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines +.. _Sphinx markup documentation: http://sphinx.pocoo.org/markup.html diff --git a/doc/hacking.txt b/doc/hacking.txt index 62919e1..fb9a7d4 100644 --- a/doc/hacking.txt +++ b/doc/hacking.txt @@ -1,11 +1,11 @@ -************* -Hacking Hooke -************* +******* +Hacking +******* .. toctree:: :maxdepth: 2 - testing.txt + testing Dependencies ============ @@ -31,10 +31,9 @@ standard library, we use configparser_ for the config files. On the testing side, the need to stick to the standard library relaxes (developers can install extra packages), so we can use nose_. See -the Testing_ section for more information. +the :doc:`testing` section for more information. .. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.3/ -.. _Testing: testing.txt Architecture diff --git a/doc/index.txt b/doc/index.txt index 4d90816..2225fcc 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -25,12 +25,12 @@ Contents: .. toctree:: :maxdepth: 2 - install.txt - tutorial.txt - config.txt - hacking.txt - hooke/hooke.txt - doc.txt + install + tutorial + config + hacking + hooke/hooke + doc Indices and tables ================== @@ -72,8 +72,8 @@ If you have troubles in using Hooke: Disclaimer ========== -Remember that Hooke is still experimental software! It has been mostly -done to fit the needs of its authors, and there is no guarantee it -will do what you need. However, you can write us/help us improve it so -that it does. We aim to make of Hooke a little, universal tool that -can help your research. +Remember that Hooke is still experimental software! It has been +mostly done to fit the needs of its authors, and there is no guarantee +it will do what you need. However, you can write us/help us improve +it so that it does. We aim to make of Hooke a little, universal tool +that can help your research. diff --git a/doc/testing.txt b/doc/testing.txt index 736d9ca..d5e9491 100644 --- a/doc/testing.txt +++ b/doc/testing.txt @@ -1,14 +1,14 @@ -************* -Testing Hooke -************* +******* +Testing +******* Hooke's test framework is build using doctest_, unittest_, and nose_. -`nosetests` (from the `nose` package) scans through the source -tree, searching out the various tests and running them. If you aren't -familiar with `nose`, there is excellent documentation on its home -page. We use `nose` because its auto-discovery allows us to avoid -collecting all of our assorted tests into `unittest.TestSuite`\s and -running them by hand. +``nosetests`` (from the nose_ package) scans through the source tree, +searching out the various tests and running them. If you aren't +familiar with nose_, there is excellent documentation on its home +page. We use nose_ because its auto-discovery allows us to avoid +collecting all of our assorted tests into +:class:`unittest.TestSuite`\s and running them by hand. To run the test suite from the Hooke installation directory, just use:: @@ -22,4 +22,4 @@ To run the test suite from the Hooke installation directory, just use:: Adding tests to modules ----------------------- -Just go crazy with doctests and unittests; `nose` will find them. +Just go crazy with doctests and unittests; nose_ will find them. diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 0d0553b..6a85383 100644 --- a/doc/tutorial.txt +++ b/doc/tutorial.txt @@ -11,24 +11,20 @@ Benedetti, EPFL, Lausanne) .. toctree:: :maxdepth: 2 - gui.txt + gui Introduction ============ This tutorial will focus on the command-line interface as the most -powerful, and leave the GUI interface to another document. +powerful, and leave the :doc:`gui` interface to another document. .. _command-line: `Command-line interface`_ -.. _GUI: gui.txt Installation ============ -See the Installation_ page for details on downloading and installing -Hooke. - -.. _Installation: install.txt +See :doc:`install` for details on downloading and installing Hooke. Command-line interface @@ -37,20 +33,19 @@ Command-line interface Running the hooke shell ----------------------- -Hooke has a set of commands that depend on the loaded plugins_. -To access these commands, you'll need to run the Hooke shell.:: +Hooke has a set of commands that depend on the loaded +:class:`hooke.plugin.Plugin`\s. To access these commands, you'll need +to run the Hooke shell.:: $ hooke If you are running hooke from the source directory (see -Installation_), the equivalent command is:: +:doc:`install`), the equivalent command is:: $ python bin/hooke You may need to give the full path for Python on Windows systems. -.. _plugins: hooke/hooke.plugin.txt - As Hooke launches, you should see something like the following in your terminal:: @@ -60,8 +55,8 @@ terminal:: ---- hooke> -The final line, `hooke>`, is the Hooke prompt. It allows you to -enter commans to interact with the interpreter. +The final line, ``hooke>``, is the Hooke prompt. It allows you to +enter commands to interact with the interpreter. Help ---- @@ -73,7 +68,7 @@ with:: hooke> help -Or see specific help on `TOPIC` with:: +Or see specific help on ``TOPIC`` with:: hooke> help TOPIC @@ -81,7 +76,7 @@ for example:: hooke> help current -will give help on the `current` command. +will give help on the ``current`` command. Creating a playlist ------------------- @@ -92,27 +87,27 @@ analyze. Imagine it as a music playlist (that’s why it is called a playlist), but with data files instead of audio files. Suppose you have 100 PicoForce curve files in your curves directory, -starting from `mycurve.000` and ending in `mycurve.100` and you -want to analyze them all. +starting from :file:`mycurve.000` and ending in :file:`mycurve.100` +and you want to analyze them all. -You then can `cd` (change directory) to the directory:: +You then can ``cd`` (change directory) to the directory:: hooke> cd c:\curves -Type `pwd` (print working directory) to check the directory is correct.:: +Type ``pwd`` (print working directory) to check the directory is correct.:: hooke> pwd c:\curves -You can list the files in the directory using `ls` or `dir` (they’re -synonyms).:: +You can list the files in the directory using ``ls`` or ``dir`` +(they’re synonyms).:: hooke> ls [’mycurve.000’, ’mycurve.001’, ... ] Now you are ready to generate the playlist. The command to use is -`genlist`.:: +``genlist``.:: hooke> genlist mycurve.* @@ -126,20 +121,20 @@ can use wildcards. For example:: hooke> genlist mycurve.05* -will take only curves from mycurve.050 to mycurve.059. +will take only curves from :file:`mycurve.050` to :file:`mycurve.059`. -Note that by using `genlist` you just generate the playlist in the +Note that by using ``genlist`` you just generate the playlist in the local session. To save your playlist to a file for future reuse, type:: hooke> savelist mylist -In this example, the list will be saved in the file `mylist.hkp`. -Hooke will add the extension `.hkp` (Hooke playlist) to the playlist -if you forget to. The `.hkp` file is an XML file you can read and -edit with any text editor (i.e. Wordpad), if needed. If you want to -load it, simply issue `loadlist mylist.hkp` or `loadlist mylist`, -Hooke will add `.hkp` if necessary. +In this example, the list will be saved in the file +:file:`mylist.hkp`. Hooke will add the extension ``.hkp`` (Hooke +playlist) to the playlist if you forget to. The ``.hkp`` file is an +XML file you can read and edit with any text editor (i.e. Wordpad), if +needed. If you want to load it, simply issue ``loadlist mylist.hkp`` +or ``loadlist mylist``, Hooke will add ``.hkp`` if necessary. If, generating the playlist, you are including by chance a non-force curve file that Hooke cannot open, Hooke will print an error and @@ -170,24 +165,23 @@ Taking notes You can take notes about the curves you are looking at. Just type `note` followed by the text you want to append to that curve. Hooke will save the text in your current playlist and in an external log -file. The output will look like this: +file. The output will look like this:: -Notes taken at Sun Sep 17 20:42:07 2006 -/home/cyclopia/work/tris/20060620a.041 | This is a note -/home/cyclopia/work/tris/20060620a.207 | This is another note -/home/cyclopia/work/tris/20060620a.286 | This is a third one + Notes taken at Sun Sep 17 20:42:07 2006 + /home/cyclopia/work/tris/20060620a.041 | This is a note + /home/cyclopia/work/tris/20060620a.207 | This is another note + /home/cyclopia/work/tris/20060620a.286 | This is a third one -The log file name can be configured_, but it defaults to hooke.log. - -.. _configured: config.txt +The log file name can be configured (:doc:`config`), but it defaults +to :file:`hooke.log`. Usually curves you annotated are useful later. You can copy the curves -you annotated to a different directory by using the `copylog` +you annotated to a different directory by using the ``copylog`` command. hooke> copylog c:\nicecurves -will copy all curves you have annotated to the c:\nicecurves +will copy all curves you have annotated to the :file:`c:\nicecurves` directory. Make sure that the directory already exists before doing that. TODO: replace with:: @@ -197,13 +191,13 @@ Exporting curves ---------------- You can export Hooke curves as images and as text columns. To export -as images, issue the `export` command followed by the filename. +as images, issue the ``export`` command followed by the filename. Supported formats are PNG (raster) and EPS (Encapsulated Postscript, -vectorial). The export format is determined by the filename -extension, so `export foo.png` and `export foo.eps` will save -PNG and EPS files respectively. +vector). The export format is determined by the filename extension, +so ``export foo.png`` and ``export foo.eps`` will save PNG and EPS +files respectively. -To export as text, use the `txt` command, followed by the +To export as text, use the ``txt`` command, followed by the filename. The output is a text file containing columns (first two are X and Y of extension, second two are X and Y of retraction). @@ -223,55 +217,55 @@ You can easily zoom in the plot by dragging a rectangle on it with the left mouse button. To zoom out, click the right mouse button. Sometimes by zooming in and out too much, you can lose the picture (this is probably a small bug in Matplotlib). Just type -`plot` at the command line and the curve will be refreshed. +``plot`` at the command line and the curve will be refreshed. You can measure distances and forces directly in the plot. Just issue -the command `distance`. You will be asked to click two points. +the command ``distance``. You will be asked to click two points. When you click a point, a blue dot should appear. When you click the second point, the distances (in nanometers and piconewtons) will -appear on the command line. You can use `delta` if you prefer, +appear on the command line. You can use ``delta`` if you prefer, which gives meaningful values for every kind of graph (not only force curves). If you want to know the coordinates of a single point, use -`point`. +``point``. Hooke automatically adjusts the position of the clicked point to the nearest point in the graph, so you will be always measuring distances and forces between points in the graph. -The commands `force` and `distance` are present in the -`generalvclamp` plugin. +The commands ``force`` and ``distance`` are present in the +``generalvclamp`` plugin. Worm like chain and freely jointed chain fitting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can measure by hand the parameters relative to a force peak using -a worm-like chain fitting with the `fit` command. The command by +a worm-like chain fitting with the ``fit`` command. The command by default automatically finds the contact point, asks for two points delimiting the portion to fit, and performs a two-variable fit, with contour length, persistence length, and their relative errors as -output. If desired, one can use the `noauto` option to manually -click the contact point, and/or the `pl=NUMBER` options to impose a +output. If desired, one can use the ``noauto`` option to manually +click the contact point, and/or the ``pl=NUMBER`` options to impose a specific persistence or Kuhn length (in nanometers). You can choose -which model to use with `set fit_function wlc` or `set fit_function -fjc`. See the help of the `fit` command from the Hooke -command line for details. +which model to use with ``set fit_function wlc`` or ``set fit_function +fjc``. See the help of the ``fit`` command from the Hooke command +line for details. Multiple curve fitting and measuring ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can cycle through all your current playlist obtaining WLC fit, FJC fit, rupture force and slope (loading rate) information from each -curve using the `multifit` command. The collected data can be saved +curve using the ``multifit`` command. The collected data can be saved in a text file for further analysis in your favourite spreadsheet or statistical program. If you want to check your parameters on the current curve before fitting all the files in your playlist, use -`multifit justone`. See the `multifit` help for more options. +``multifit justone``. See the ``multifit`` help for more options. Fast curve reviewing and saving ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When automatic routines are not good enough to filter your data, use -`review` command to cycle through your playlist presenting ten +``review`` command to cycle through your playlist presenting ten curves in the same graph. You can then enter the numbers of the interesting curves and automatically save a copy of them into another directory. @@ -280,10 +274,8 @@ Configuring Hooke ----------------- You can set environment variables to influence the behaviour of -Hooke. The command to use is `set`. +Hooke. The command to use is ``set``. You can alter permanently the behaviour of Hooke by setting these -variables in a Hooke configuration file. See the `Configuring Hooke`_ -section for details. - -.. _Configuring Hooke: config.txt +variables in a Hooke configuration file. See :doc:`config` for +details. -- 2.26.2