1. grainednoise
  2. sphinx_usecases

Commits

grainednoise  committed c41683d

Add install document

  • Participants
  • Parent commits 1b32174
  • Branches default

Comments (0)

Files changed (1)

File documentation/usage.rst

View file
  • Ignore whitespace
+==================================================
+Installing and configuring ``sphinx-usecases``
+==================================================
+
+
+Distribution
+-----------------------------------------
+
+Firstly, this module is not on ``pypi`` yet. I'd like the module to
+acquire a few more features, and be more confident about its stability
+before going mainstream. So, at the moment it can only be 
+downloaded (or cloned) from:
+
+   https://bitbucket.org/grainednoise/sphinx_usecases
+
+
+
+
+Dependencies
+-----------------------------------------
+
+The module is dependent on ``Sphinx`` version 1.0.7 or
+higher. (This, in turn, has several dependencies,
+notably ``doctools``\, ``jinja2`` and ``pygments``.)
+
+
+
+
+Install
+-----------------------------------------
+
+The module is pure Python, and consists of only a handful
+of files. As such, you can even use the module
+:ref:`without installing <usage no install>` it altogether,
+provided ``Sphinx`` is already on your system. You'll find the
+more common installation methods below.
+
+
+
+Using ``distutils``
+_________________________________________
+
+
+The module has a standard `distutils` installer,
+so
+
+::
+
+   python setup.py install
+
+
+should get the job done.
+
+
+.. note::
+   Running on Unix-like OSes, you'll most likely need root privileges, so either
+   prefix your commands with ``sudo`` or start up a root shell.
+
+
+Using ``easy_install``
+_________________________________________
+
+
+Sorry, the module's not yet up on ``pypi``. However, you could
+use ``easy_install`` to install ``pip``, and then you could
+use the method below.
+
+
+
+Using ``pip``
+_________________________________________
+
+
+If you have both ``pip`` *and* ``mercurial`` on your system, and 
+have a working internet connection, there's an alternative
+way of installing the module::
+
+
+   pip install hg+http://bitbucket.org/grainednoise/sphinx_usecases
+
+
+This will also install any dependencies, if not already present on
+the system. If you want to upgrade to a newer version, use::
+
+   pip install -U hg+http://bitbucket.org/grainednoise/sphinx_usecases
+
+
+This does, however, has the side effect of upgrading not only ``sphinx_usecases``,
+but *all* its direct and indirect dependencies, so it'll take a bit longer.
+
+
+.. note::
+   Running on Unix-like OSes, you'll most likely need root privileges, so either
+   prefix your commands with ``sudo`` or start up a root shell.
+
+
+Is it installed properly?
+_________________________________________
+
+
+A very simple way to check this is to fire up the Python interactive
+interpreter and try to import the library:
+
+
+.. code-block:: python
+
+   Python 2.6.4 (r264:75708, Oct 26 2009, 08:23:19) [MSC v.1500 32 bit (Intel)] on win32
+   Type "help", "copyright", "credits" or "license" for more information.
+   >>> import sphinx_usecases
+   >>>
+
+When you see this, everything is ok. On the other hand, if you're greeted with:
+
+
+.. code-block:: python
+
+   Python 2.6.4 (r264:75708, Oct 26 2009, 08:23:19) [MSC v.1500 32 bit (Intel)] on win32
+   Type "help", "copyright", "credits" or "license" for more information.
+   >>> import sphinx_usecases
+   Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+   ImportError: No module named sphinx_usecases
+   >>>
+
+
+things are definitely *not* good. Check the ``site-packages`` directory in your Python installation,
+and make sure thatat the very least the directory ``sphinx_usecases`` is present. (Typically, you'll also find
+a directory like ``sphinx_usecases-0.0.1-py2.6.egg-info``\.) If not, try and see if re-installing it helps,
+perhaps using another method.
+
+
+
+Configure
+-----------------------------------------
+
+Basic
+_________________________________________
+
+As with all Sphinx extensions, you have to confugure your
+documentation project to actually use it. Simply adding
+``sphinx_usecases`` to the list of extensions should do
+the trick. Example usage:
+
+
+.. code-block:: python
+
+   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx_usecases']
+
+
+
+Extra options
+_________________________________________
+
+There are a few extra options you may add to ``conf.py``. These are mostly for
+debuging purposes, so they're unlike to be very useful to you:
+
+
+* ``usecase_dump_usecases_to``
+
+   This option is ``None`` by default. When set to anything else, it will be
+   interpreted as a file name, and the module will attempt to write all
+   collected usecases to that file in `json` format. Currently, no checks
+   are done whatsoever as to the content of the option, so be careful.
+   Example usage: 
+
+.. code-block:: python
+
+   usecase_dump_usecases_to = r'D:\dumps\usecases.json'
+
+
+* ``usecase_log_verbosely``
+
+   This option is ``False`` by default. Setting it to ``True`` will cause the module
+   to log a lot of extra information to the screen, often drowning warnings and
+   error messages. Only useful for debugging. Example usage:
+
+
+.. code-block:: python
+
+   usecase_log_verbosely = True
+
+
+
+.. _usage no install:
+
+Usage without installing
+-----------------------------------------
+
+If, for whatever reason, you don't wish to install the module,
+but want to use it anyway, you can perform some python path
+manipulations in your documentation project's ``conf.py`` to 
+allow Sphinx to find it. This entails the following steps:
+
+* Download and extract `sphinx-usecases` somewhere on you hard drive.
+
+* Note the full path to the ``src`` directory. This is the directory
+  which *contains* the ``sphinx_usecases`` directory.
+
+* In the ``conf.py`` of your documentation project, add it to the 
+  python path, for instance by adding:
+
+.. code-block:: python
+
+   import sys
+   full_path_to_src = r'/where/extracted/src'
+   sys.path.insert(0, full_path_to_src)
+
+
+* Don't forget to add `sphinx_usecases` to the list of extensions, e.g:
+
+
+.. code-block:: python
+
+   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx_usecases']
+
+
+This trick should also work if you already installed ``sphinx-usecases``
+but quickly want to try out a different version, e.g. to see if a bug
+has been solved in a newer version, as the path is inserted before the
+existing ones. Having said that, if that is a common scenario, using
+``virtualenv`` is a much better option.
+