Merge pull request #68 from tobinus/improve-docs

Improve docs for 1.0.1

Author: tobinus

.gitignore

@@ -6,6 +6,9 @@ venv
 # JetBrains IDE
 .idea/
 
+# Visual Studio Code
+.vscode/
+
 # Documentation build
 /doc/_build
 /docs
@@ -15,4 +18,3 @@ venv
 /MANIFEST
 /build
 /podgen.egg-info
-

CHANGELOG.md

@@ -10,11 +10,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - This `CHANGELOG.md` file, for documenting notable changes.
+- Documentation page about PodGen's roadmap (under Background).
+
+### Changed
+
+- Organization of the documentation, along with other documentation
+  improvements and updates.
 
 ### Removed
 
-- Support for Python 3.3, due to its age and lack of support, and bugs with
-  installing `tinytag`.
+- Support for Python 3.3, due to its age and lack of support.
 
 ### Fixed
 

doc/_static/custom.css

@@ -1,15 +1,40 @@
-body, div.body {
+body {
     background-color: #fffded;
 }
+div.documentwrapper, div.body {
+    background: initial;
+}
 pre {
     background-color: #ebebeb;
 }
-div.sphinxsidebar a.current {
+div.sphinxsidebar a:link.current, div.sphinxsidebar a:visited.current {
+    color: rgba(0, 0, 0, 0.9);
     text-decoration: none;
     border-bottom: none;
     font-weight: bold;
     cursor: text;
 }
+div.body {
+    min-width: auto;
+}
+div.document, div.footer {
+    width: auto;
+    max-width: 1000px;
+}
+a:link,
+div.sphinxsidebar a:link {
+    color: #004B6B;
+}
+a:visited, div.sphinxsidebar a:visited {
+    color: #56006B;
+}
+a.current + ul a[href*="#"] {
+    color: rgba(0, 0, 0, 0.9);
+}
+div.toctree-wrapper a[href*="#"]
+{
+    color: rgba(0, 28, 40, 0.65);
+}
 /* Don't hide logo when viewed on mobile, just invert its colors */
 @media screen and (max-width: 875px) {
     div.sphinxsidebar p.logo {
@@ -18,4 +43,19 @@ div.sphinxsidebar a.current {
         width: 60%;
         margin: auto;
     }
+
+    /* Different link colors */
+    div.sphinxsidebar a:link {
+        color: #BFD2DA;
+    }
+
+    div.sphinxsidebar a:visited {
+        color:  #C09FC7;
+    }
+
+    a.current + ul a[href*="#"],
+    div.sphinxsidebar a:link.current,
+    div.sphinxsidebar a:visited.current {
+        color: rgba(255, 255, 255, 0.95);
+    }
 }

doc/user/fork.rst renamed to doc/background/fork.rst

@@ -10,7 +10,7 @@ request which removes 70% of the features ;-) Among other things, support for AT
 Dublin Core is removed, and the remaining code is almost entirely rewritten.
 
 A more detailed reasoning follows. Read it if you're interested, but feel free
-to skip to :doc:`basic_usage_guide/part_1`.
+to skip to the :doc:`/usage_guide/index`.
 
 Inspiration
 -----------
@@ -46,11 +46,9 @@ and you as a user shouldn't need to know all this. You just need to know that th
 image must be larger than 1400x1400 pixels, not the history behind everything.
 
 Forking a project gives you a lot of freedom, since you don't have to support
-any old behaviour. python-feedgen_ cannot make backwards incompatible changes,
-since many projects around the earth rely on the way the library works, and you
-cannot expect everyone to use ``pip freeze`` (you should, though!). Whenever a
-change *is* appropriate for python-feedgen_, however, we should strive to bring
-it there so it can benefit as many as possible :)
+any old behaviour. It would be difficult to make these changes upstream, since
+many of the problems are inherent to the scope and purpose of the library itself,
+and changing that is difficult and not always desirable.
 
 
 Summary of changes
@@ -93,7 +91,7 @@ The following list is not exhaustive.
 * :attr:`.Podcast.explicit` is now required, and is :obj:`bool`.
 * Add shorthand for generating the RSS: Just try to converting your :class:`~podgen.Podcast`
   object to :obj:`str`!
-* Expand the documentation (as you've surely noticed).
+* Expand the documentation.
 * Move away from the extension framework, and rely on class inheritance instead.
 
 .. _python-feedgen: https://github.com/lkiesow/python-feedgen

doc/background/index.rst

@@ -0,0 +1,14 @@
+==========
+Background
+==========
+
+Learn about the "why" and "how" of the PodGen project itself.
+
+.. toctree::
+   :maxdepth: 1
+
+   philosophy
+   scope
+   fork
+   roadmap
+   license

doc/background/license.rst

@@ -0,0 +1,9 @@
+-------
+License
+-------
+PodGen is licensed under the terms of both the FreeBSD license and the LGPLv3+.
+Choose the one which is more convenient for you. For more details, have a look
+at license.bsd_ and license.lgpl_.
+
+.. _license.bsd: https://github.com/tobinus/python-podgen/blob/master/license.bsd
+.. _license.lgpl: https://github.com/tobinus/python-podgen/blob/master/license.lgpl

doc/background/philosophy.rst

@@ -0,0 +1,31 @@
+----------
+Philosophy
+----------
+
+This project is heavily inspired by the "for humans" approach of the
+`Requests <https://requests.readthedocs.io>`__ library, which features an API that
+is designed to give the developer a great user experience. This is done by
+finding a suitable scope and abstraction level, and designing the
+API so it supports the developer's vocabulary and their mental model of how
+the domain works.
+
+For example, instead of using the names of XML tags like "itunes:image", a more
+relevant name, here simply "image", is used. Another example is the duration of
+a podcast episode. In XML terms, this is put into an "itunes:duration" tag which exists
+outside of the "enclosure" tag, which holds the filename and file size. In PodGen,
+the filename, file size, file type and audio duration are all placed together in
+a Media instance, since they are all related to the media itself. The goal
+has been to "hide" the messy details of the XML and provide an API on top which
+uses words that you recognize and use daily when working with podcasts.
+
+To be specific, PodGen aims to follow the same
+`PEP 20 <https://www.python.org/dev/peps/pep-0020/>`__ idioms as
+`Requests <https://requests.readthedocs.io/en/master/user/intro/#philosophy>`__:
+
+1. Beautiful is better than ugly.
+2. Explicit is better than implicit.
+3. Simple is better than complex.
+4. Complex is better than complicated.
+5. Readability counts.
+
+To enable this, the project focuses on one task alone: making it easy to generate a podcast.

doc/background/roadmap.rst

@@ -0,0 +1,42 @@
+-------
+Roadmap
+-------
+
+When PodGen reaches a certain point where it has all the features it needs,
+while still being simple to use, it would not be necessary with further
+updates… had it not been for changes to PodGen's dependencies and changes to
+the overall podcast standards. Luckily, the applications that read podcasts
+tend to be backwards compatible, in order to support all the old podcasts that
+are out there.
+
+The current plan for PodGen updates is as follows:
+
+* **New minor version**: Support for the new Apple Podcast specifications and
+  categories, as much as is possible without breaking backwards compatibility.
+* Deprecation warnings for properties and such which will be removed in the
+  next major version.
+* **New major version**: Support for the new Apple Podcast specifications and
+  categories which could not be included earlier due to backwards compatibility,
+  or which have new names or behaviours to simplify the API. Removal of
+  deprecated features.
+* **New minor versions**: Removal of support for Python releases that have
+  passed `End of Life`_ (Python 2.7 after January 1st 2020, Python
+  3.4), allowing for simplifications and use of new features in the code base.
+  Other code and documentation improvements should hopefully stop PodGen from
+  becoming stale and burdensome to maintain.
+* Better ways of adding support for RSS features which PodGen itself does not
+  support.
+
+.. _End of life: https://devguide.python.org/#status-of-python-branches
+
+Unlike other libraries with evolving demands, PodGen is expected to stay
+relatively stable with the occasional update. Changes to the Apple Podcast
+specifications do not occur particularly often, so PodGen won't need to change
+often either.
+
+Since PodGen is an open source project and its maintainer has a limited amount
+of time to spare, updates may be sporadic. Despite this, please don't hesitate
+to report issues or feature requests if there is something that does not
+work or you feel should be included. The project is used by the Student Radio
+of Trondheim and will be kept up-to-date with their requirements, though they
+are not primarily a podcast producer.

doc/background/scope.rst

@@ -0,0 +1,31 @@
+-----
+Scope
+-----
+
+This library does NOT help you publish a podcast, or manage the metadata of your
+podcasts. It's just a tool that accepts information about your podcast and
+outputs an RSS feed which you can then publish however you want.
+
+Both the process of getting information
+about your podcast, and publishing it needs to be done by you. Even then,
+it will save you from hammering your head over confusing and undocumented APIs
+and conflicting views on how different RSS elements should be used. It also
+saves you from reading the RSS specification, the RSS Best Practices and the
+documentation for iTunes' Podcast Connect.
+
+Here is an example of how PodGen fits into your code:
+
+1. A request comes to your webserver (using e.g. `Flask <https://palletsprojects.com/p/flask/>`__)
+2. A podcast router starts to handle the request.
+3. The database is queried for information about the requested podcast.
+4. **The data retrieved from the database is "translated" into the language of PodGen, using its Podcast, Episode, People and Media classes.**
+5. **The RSS document is generated by PodGen and saved to a variable.**
+6. The generated RSS document is made into a response and sent to the client.
+
+PodGen is geared towards developers who aren't super familiar with
+RSS and XML. If you know exactly how you want the XML to look, then you're
+better off using a template engine like Jinja2 (even if friends don't let
+friends touch XML bare-handed) or an XML processor like the built-in
+`Python ElementTree API <https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree>`__.
+If you just want an easy way to create and manage your podcasts,
+check out systems like `Podcast Generator <http://www.podcastgenerator.net/>`_.

doc/conf.py

@@ -45,7 +45,7 @@
 
 # General information about the project.
 project = u'PodGen'
-copyright = u'2014, Lars Kiesow. Modified work © 2016, Thorben Dahl'
+copyright = u'2014, Lars Kiesow. Modified work © 2019, Thorben Dahl'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -112,11 +112,19 @@
     'gray_2': "rgba(0, 0, 0, 0.2)",
     'gray_3': "rgba(198, 198, 198, 0.9)",
 
+    'description': 'Generate podcasts with ease.',
+    'show_relbars': True,
+
     'github_user': 'tobinus',
     'github_repo': 'python-podgen',
-    'github_banner': True,
     'logo_name': False,
     'logo': 'logo.png',
+
+    'extra_nav_links': {
+        'Changelog': 'https://github.com/tobinus/python-podgen/blob/master/CHANGELOG.md',
+        'GitHub': 'https://github.com/tobinus/python-podgen/tree/master',
+        'PyPI': 'https://pypi.org/project/podgen/',
+    },
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -278,7 +286,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'requests': ('http://docs.python-requests.org/en/master', None)}
+                       'requests': ('https://requests.readthedocs.io/en/master', None)}
 
 
 # Ugly way of setting tabsize

doc/contributing.rst

@@ -35,9 +35,9 @@ The unit tests reside in ``podgen/tests`` and are written using the
 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.
+Read :doc:`/background/philosophy`, :doc:`/background/scope` and :doc:`/background/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