Skip to content
This repository has been archived by the owner on Jan 26, 2018. It is now read-only.

Sphinx extension for STScI. THIS REPOSITORY IS ARCHIVED.

Notifications You must be signed in to change notification settings

spacetelescope/stsci.sphinxext

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

34 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

stsci.sphinxext
===============

:author: Michael Droettboom, 2011

Purpose
-------

This project contains extensions to Sphinx to build documentation from STScI.

Prerequisites
-------------

- Sphinx 0.6.3 or later, and its dependencies

- numpydoc - provides support for Numpy-style docstring syntax

  - The version shipped with Numpy 1.4.0 or later is required

- matplotlib - provides matplotlib extensions for inline plotting

These requirements are not listed in the installation requirements in the
metadata simply because numpy and matplotlib in particular are large and not
easy to deal with, so trying to install a Sphinx theme should not have the
side-effect of trying to install these prerequisites as well.

Usage
-----

These instructions only cover changes from the standard Sphinx
instructions.

Create a new tree for your Sphinx documentation, using
sphinx_quickstart, as described in the `Sphinx introduction
<http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources>`_.

Import the stsci_sphinx customizations into your project's `conf.py`
by inserting the following line at the top::

  from stsci.sphinxext.conf import *

The "extensions" line in your `conf.py` should also be modified so it
doesn't override the extensions defined by stsci.sphinxext.  For
example, change::

  extensions = ['sphinx.ext.autodoc']

to::

  extensions += ['sphinx.ext.autodoc']

Also, comment out the 'html_theme' line, so your project will use the
stsci.sphinxext one.