Skip to main content

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.

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.

Project details


Download files

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

Source Distribution

sphinx-me-0.3.tar.gz (5.7 kB view details)

Uploaded Source

Built Distribution

sphinx_me-0.3-py2.py3-none-any.whl (7.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file sphinx-me-0.3.tar.gz.

File metadata

  • Download URL: sphinx-me-0.3.tar.gz
  • Upload date:
  • Size: 5.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for sphinx-me-0.3.tar.gz
Algorithm Hash digest
SHA256 98bef823a4053ca1ccbbe2322bd855a3c5e98797c50bcfeeb630fe11c47d5f1a
MD5 a0b11069d808a6bc4a8e533abff7bc02
BLAKE2b-256 1505fa421fa08ab98342b71371117af7197ff130ef6dc7d7646c60a91e9d7eeb

See more details on using hashes here.

File details

Details for the file sphinx_me-0.3-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_me-0.3-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 2c67a6bbf9d60631a84b687f0bafbfe2cb16e2663deee28ce03d5f07c7d89807
MD5 e7b4bff5817fd5c53063d529e62d9a75
BLAKE2b-256 d05419bc2492a652450bad1faa1de5f4d722bd6965ab2ad5f2c5f3ef9304a930

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page