Jannis Leidel avatar Jannis Leidel committed dd8f28e

Added README and bumped version up to do a release

Comments (0)

Files changed (2)

+Sphinx-PyPI-upload
+==================
+
+This package contains a `setuptools`_ command for uploading `Sphinx`_
+documentation to the `Python Package Index`_ (PyPI) at the dedicated URL
+packages.python.org.
+
+.. _setuptools: http://pypi.python.org/pypi/setuptools
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _`Python Package Index`: http://pypi.python.org/
+
+
+The ``upload_sphinx`` command
+------------------------------
+
+``upload_sphinx`` will create the necessary zip file out of an arbitrary 
+documentation directory and posts it to the correct URL.
+
+It's also loosely based on Sphinx' own setuptools command build_sphinx_
+which allows to easily build documentation from the command line.
+
+The ``upload_sphinx`` command has the following options:
+
+- ``--repository (-r)``:
+  url of repository [default: http://pypi.python.org/pypi]
+
+- ``--show-response``:
+  display full response text from server
+
+- ``--upload-dir``:
+  directory to upload
+
+.. _build_sphinx: http://bitbucket.org/birkenfeld/sphinx/src/tip/sphinx/setup_command.py
+
+Example
+--------
+
+Assuming there is an ``Example`` package with Sphinx documentation to be
+uploaded to http://packages.python.org, with the following structure::
+
+  Example/
+  |-- example.py
+  |-- setup.cfg
+  |-- setup.py
+  |-- docs
+  |   |-- build
+  |   |   `-- html
+  |   |-- conf.py
+  |   |-- index.txt
+  |   `-- tips_tricks.txt
+
+As with any other setuptools based command, you can define useful defaults in
+the setup.cfg of your Python package. The following snippet shows how to set
+the option defaults of the ``build_sphinx`` and ``upload_sphinx`` setup.py 
+commands::
+
+  [build_sphinx]
+  source-dir = docs/
+  build-dir  = docs/build
+  all_files  = 1
+
+  [upload_sphinx]
+  upload-dir = docs/build/html
+
+To build and upload the Sphinx documentation you are now able to run::
+
+  $ python setup.py build_sphinx
+  $ python setup.py upload_sphinx
+
+Alternatively, you can of course just pass the appropriate options directly
+to the commands::
+
+  $ python setup.py build_sphinx --source-dir=docs/ --build-dir=docs/build --all-files
+  $ python setup.y upload_sphinx --upload-dir=docs/build/html
 from setuptools import setup
 
+def read(fname):
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
 setup(
     name="Sphinx-PyPI-upload",
-    version='0.2',
+    version='0.2.1',
     author="Jannis Leidel",
     author_email="jannis@leidel.info",
     url="http://bitbucket.org/jezdez/sphinx-pypi-upload/",
     download_url="http://bitbucket.org/jezdez/sphinx-pypi-upload/downloads/",
     description="setuptools command for uploading Sphinx documentation to PyPI",
+    long_description=read('README'),
     license="BSD",
     classifiers=[
         "Topic :: Documentation",
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.