Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Wraps your README-only projects in a dynamic Sphinx shell for hosting on http://readthedocs.org

Project Description

Created by Stephen McDonald

Introduction

Do you have smaller Python projects that only need a README file for documentation? Want to host your README on Read The Docs?

sphinx-me is a BSD licensed tool that will create a Sphinx documentation shell for your project and include the README file as the documentation index. It handles extracting the required meta data such as the project name, author and version from your project for use in your Sphinx docs.

Once you use sphinx-me to build your Sphinx docs, you can then add your project to the Read The Docs site and have your project’s README hosted with an attractive Sphinx documentation theme.

Note

Your README file should be in a reStructuredText compatible format.

Installation

The easiest way to install sphinx-me is directly from PyPI using pip or setuptools by running the respective command below:

$ pip install -U sphinx-me

or:

$ easy_install -U sphinx-me

Otherwise you can download sphinx-me and install it directly from source:

$ python setup.py install

Running

sphinx-me will be installed as a system-wide script that can be run from the command line while in your project’s root directory:

$ sphinx-me

When run in your project’s directory, it will create a docs directory with two files, the Sphinx conf.py module, and an index.rst file which will include your project’s README.

The conf.py module calls a setup function from sphinx-me that sets up the minimum required settings for your Sphinx docs.

  • project - the directory name of your project is used.
  • version - retrieved from the version arg of your setup.py script, or your package’s __version__ attribute.
  • copyright - retrieved from the author arg of your setup.py script, or your package’s __author__ attribute.

Running this process will also perform an initial sphinx-build inside your project’s docs/build directory. Subsequent builds after making changes to your README can be performed by running sphinx-me again, or by using the regular sphinx-build command.

Hosting on Read The Docs

When hosting your sphinx-me generated docs on Read The Docs, you must ensure you check the Use virtualenv option and specify sphinx-me as a requirement in either your setup.py script, or in a pip requirements file that you’ll need to also specify in the Requirements file field for your project on Read The Docs.

Release History

Release History

This version
History Node

0.3

History Node

0.2.1

History Node

0.2.0

History Node

0.1.2

History Node

0.1.1

History Node

0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sphinx_me-0.3-py2.py3-none-any.whl (7.5 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Aug 3, 2014
sphinx-me-0.3.tar.gz (5.7 kB) Copy SHA256 Checksum SHA256 Source Aug 3, 2014

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting