Merge pull request #24 from tobinus/refactor-documentation-#8

Refactor documentation, closes #8

Author: tobinus

doc/_static/custom.css

@@ -4,3 +4,18 @@ body, div.body {
 pre {
     background-color: #ebebeb;
 }
+div.sphinxsidebar a.current {
+    text-decoration: none;
+    border-bottom: none;
+    font-weight: bold;
+    cursor: text;
+}
+/* Don't hide logo when viewed on mobile, just invert its colors */
+@media screen and (max-width: 875px) {
+    div.sphinxsidebar p.logo {
+        display: block;
+        filter: invert(100%);
+        width: 60%;
+        margin: auto;
+    }
+}

doc/api.rst

@@ -1,28 +1,6 @@
 =================
-Developer's Guide
-=================
-
-
--------
-Testing
--------
-
-You can test the module integration-testing-style by simply executing::
-
-    $ python -m podgen
-
-When working on this project, you should run the unit tests as well as the
-integration test, like this::
-
-    $ make test
-
-The unit tests reside in ``podgen/tests`` and are written using the
-:mod:`unittest` module.
-
-
------------------
 API Documentation
------------------
+=================
 
 .. autosummary::
 

doc/conf.py

@@ -16,7 +16,10 @@
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.4'
+
+# Don't show warnings about the button images not being local
+suppress_warnings = ['image.nonlocal_uri']
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -103,12 +106,11 @@
     'fixed_sidebar': False,
     'page_width': "1000px",
     'sidebar_width': "225px",
-    'show_related': True,
     'body_text': "rgba(0, 0, 0, 0.8)",
     'footer_text': "rgba(0, 0, 0, 0.5)",
     'gray_1': "rgba(0, 0, 0, 0.9)",
     'gray_2': "rgba(0, 0, 0, 0.2)",
-    'gray_3': "rgba(0, 0, 0, 0.1)",
+    'gray_3': "rgba(198, 198, 198, 0.9)",
 
     'github_user': 'tobinus',
     'github_repo': 'python-podgen',
@@ -134,7 +136,7 @@
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = "favicon.ico"
+html_favicon = "_static/favicon.ico"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -215,13 +217,13 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    ('index', 'pyPodGen.tex', u'pyPodGen Documentation',
-        u'Lars Kiesow', 'manual'),
+    ('index', 'pyPodGen.tex', u'PodGen Documentation',
+        u'Lars Kiesow and Thorben Dahl', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+latex_logo = '_static/logo.png'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -231,13 +233,13 @@
 #latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-#latex_show_urls = False
+latex_show_urls = "true"
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
-#latex_domain_indices = True
+latex_domain_indices = False
 
 
 # -- Options for manual page output --------------------------------------------
@@ -250,7 +252,7 @@
 ]
 
 # If true, show URL addresses after external links.
-#man_show_urls = False
+man_show_urls = True
 
 
 # -- Options for Texinfo output ------------------------------------------------
@@ -275,7 +277,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 
 # Ugly way of setting tabsize

doc/contributing.rst

@@ -0,0 +1,92 @@
+============
+Contributing
+============
+
+Setting up
+----------
+
+To install the dependencies, run::
+
+    $ pip install -r requirements
+
+while you have a `virtual environment <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_
+activated.
+
+You are recommended to use `pyenv <https://github.com/yyuu/pyenv>`_ to handle
+virtual environments and Python versions. That way, you can easily test and
+debug problems that are specific to one version of Python.
+
+Testing
+-------
+
+You can perform an integration test by running ``podgen/__main__.py``::
+
+    $ python -m podgen
+
+When working on this project, you should run the unit tests as well as the
+integration test, like this::
+
+    $ make test
+
+The unit tests reside in ``podgen/tests`` and are written using the
+:mod:`unittest` module.
+
+
+Values
+------
+
+Read :doc:`/user/introduction` and :doc:`/user/fork` for a run-down on what
+values/principles lay the foundation for this project. In short, it is important
+to keep the API as simple as possible.
+
+You must also write unittests as you code, ideally using **test-driven
+development** (that is, write a test, observe that the test fails, write code
+so the test works, observe that the test succeeds, write a new test and so on).
+That way, you know that the tests actually contribute and you get to think
+about how the API will look before you tackle the problem head-on.
+
+Make sure you update ``podgen/__main__.py`` so it still works, and use your new
+functionality there if it makes sense.
+
+You must also make sure you **update any relevant documentation**. Remember that
+the documentation includes lots of examples and also describes the API
+independently from docstring comments in the code itself.
+
+Pull requests in which the unittests and documentation are NOT up to date
+with the code will NOT be accepted.
+
+Lastly, a single **commit** shouldn't include more changes than it needs. It's better to do a big
+change in small steps, each of which is one commit. Explain the impact of your
+changes in the commit message.
+
+The Workflow
+------------
+
+#. Check out `waffle.io <https://waffle.io/tobinus/python-podgen>`_ or
+   `GitHub Issues <https://github.com/tobinus/python-podgen/issues>`_.
+
+   * Find the issue you wish to work on.
+   * Add your issue if it's not already there.
+   * Discuss the issue and get feedback on your proposed solution. Don't waste
+     time on a solution that might not be accepted!
+
+#. Work on the issue in a separate branch which follows the name scheme
+   ``tobinus/python-podgen#<issue-number>-<brief-description>`` in your own fork. To be honest, I
+   don't know if Waffle.io will notice that, but it doesn't hurt to try, I
+   guess! You might want to read up on `Waffle.io's recommended workflow <https://github.com/waffleio/waffle.io/wiki/Recommended-Workflow-Using-Pull-Requests-&-Automatic-Work-Tracking>`_.
+
+#. Push the branch.
+
+#. Do the work.
+
+#. When you're done and you've updated the documentation and tests (see above),
+   create a pull request which references the issue.
+
+#. Wait for me or some other team member to review the pull request. Keep an
+   eye on your inbox or your GitHub notifications, since we may have some
+   objections or feedback that you must take into consideration. **It'd be a
+   shame if your work never led to anything because you didn't notice a
+   comment!**
+
+#. Consider making the same changes to `python-feedgen <https://github.com/lkiesow/python-feedgen>`_
+   as well.

doc/index.rst

@@ -9,46 +9,53 @@ PodGen
    :target: http://podgen.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 
-Wouldn't it be nice if there was a **clean and simple library** which could help you
-**generate podcast RSS feeds** from your Python code? Well, today's your lucky day!
+.. image:: https://badge.waffle.io/tobinus/python-podgen.svg?label=ready&title=Ready
+   :target: https://waffle.io/tobinus/python-podgen
+   :alt: 'Stories in Ready'
+
+Don't you wish there was a **clean and simple library** which could help you
+**generate podcast RSS feeds** with your Python code? Well, today's your lucky day!
 
    >>> from podgen import Podcast, Episode, Media
    >>> # Create the Podcast
    >>> p = Podcast(
-          name="My Awesome Podcast",
+          name="The Library Tuesday Talk",
           description="My friends and I discuss Python"
                       " libraries each Tuesday!",
-          website="http://example.org/awesomepodcast"
+          website="http://example.org/librarytuesdaytalk"
        )
    >>> # Add some episodes
    >>> p.episodes += [
-          Episode(title="PodGen rocks!",
+          Episode(title="Worry about timezones no more",
                   media=Media("http://example.org/ep1.mp3", 11932295),
-                  summary="I found an awesome library for creating podcasts"),
+                  summary="Using pytz, you can make your code timezone-aware "
+                          "with very little hassle."),
           Episode(title="Heard about clint?",
                   media=Media("http://example.org/ep2.mp3", 15363464),
                   summary="The man behind Requests made something useful "
-                          "for us command-line lovers."
+                          "for us command-line nerds."
        ]
    >>> # Generate the RSS feed
    >>> rss = str(p)
 
 You don't need to read the RSS specification, write XML by hand or wrap your
-head around ambiguous, undocumented APIs. Just provide the data, and PodGen
-fixes the rest for you!
-
-Where to start
---------------
+head around ambiguous, undocumented APIs. PodGen incorporates the industry's
+best practices and lets you focus on collecting the necessary metadata and
+publishing the podcast.
 
-Take a look at the :doc:`user/example` for a larger example, read about
-:doc:`the project's background <user/introduction>` or refer to
-the :doc:`user/basic_usage_guide/index` for a detailed introduction to PodGen.
 
-Contents
---------
+User Guide
+----------
 
 .. toctree::
    :maxdepth: 3
 
-   user/index
+   user/introduction
+   user/installation
+   user/fork
+   user/basic_usage_guide/part_1
+   user/basic_usage_guide/part_2
+   user/basic_usage_guide/part_3
+   user/example
+   contributing
    api