fead: add documentation pages and readme.md

CHANGES.rst

@@ -0,0 +1,8 @@
+.. currentmodule:: genrss
+
+Version 1.0.0
+-------------
+
+Released 2019-07-23
+
+-   First public preview release.

Pipfile.lock

@@ -228,10 +228,11 @@
         },
         "docutils": {
             "hashes": [
-                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521"
+                "sha256:554158db07870b514e8df93800e95ee8fbf2a2388eb453c7f69206532a8a6fa5",
+                "sha256:82725b1051b92aaa42e240a4e5d6fafa2f6f5a2b5023b23a51c941dd7d863369"
             ],
             "index": "pypi",
-            "version": "==0.15.post1"
+            "version": "==0.15.1"
         },
         "enum34": {
             "hashes": [
@@ -340,7 +341,7 @@
                 "sha256:2156525d6576d21c4dcaddfa427fae887ef89a7a9de5cbfe0728b3aafa78427e",
                 "sha256:446014523bb9be5c28128c4d2a10ad6bb60769e78bd85658fe44a450674e0ef8"
             ],
-            "markers": "python_version < '3.6'",
+            "markers": "python_version == '3.4.*' or python_version < '3'",
             "version": "==2.3.4"
         },
         "pluggy": {

README.md

@@ -4,3 +4,40 @@
 [![Coverage Status](https://coveralls.io/repos/github/icetemple/genrss/badge.svg?branch=master)](https://coveralls.io/github/icetemple/genrss?branch=master)
 
 RSS generator for python
+
+
+## Installing
+
+Install and update using pip:
+
+``pip install genrss``
+
+
+## A Simple Example
+
+```python
+from datetime import datetime
+from genrss import GenRSS
+
+feed = GenRSS(title='SmartFridge',
+			  site_url='https://smartfridge.me',
+			  feed_url='https://smartfridge.me/feed/rss.xml')
+
+feed.item(title='black buns for burgers',
+		  description='For the first time black burgers appeared ' \
+					  'in Japan. Unusual dark color buns complemented ' \
+					  'with black cheese and sauce. Over time, the dish ' \
+					  'has conquered the whole world. The main secret ' \
+					  'ingredient in popular buns is the most common... ' \
+					  'charcoal!',
+		  url='https://smartfridge.me/recipe/316b28-chernye-bulochki-dlya-burgerov/',
+		  author='@smartfridge',
+		  categories=['baking'],
+		  pub_date=datetime.utcnow())
+
+xml = feed.xml()
+```
+
+## Links
+
+Documentation: [https://genrss.readthedocs.io/en/latest/](https://genrss.readthedocs.io/en/latest/)

docs/Makefile

@@ -13,10 +13,6 @@ help:
 
 .PHONY: help Makefile
 
-github:
-	@make html
-	@cp -a _build/html/. .
-
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/_templates/localtoc.html

@@ -0,0 +1,2 @@
+<h3>Contents</h3>
+{{ toc }}

docs/_templates/navigations.html

@@ -0,0 +1,13 @@
+<h3>Navigation</h3>
+<ul>
+  <li><a href="{{ pathto(master_doc) }}">Overview</a>
+    {% if parents or prev or next %}<ul>{% for parent in parents %}
+      <li><a href="{{ parent.link|e }}">{{ parent.title }}</a>
+        {% if not loop.last or (prev or next) %}<ul>{% endif %}{% endfor %}
+          {% if prev %}<li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter') }}">{{ prev.title }}</a>{% endif %}
+          {% if next %}<li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter') }}">{{ next.title }}</a>{% endif %}
+        {%- for parent in parents %}</ul>
+      </li>{% endfor %}
+    </ul>{% endif %}
+  </li>
+</ul>

docs/api.rst

@@ -0,0 +1,9 @@
+.. _api:
+
+API
+===
+
+.. automodule:: genrss
+
+.. autoclass:: GenRSS
+   :members:

docs/changelogs.rst

@@ -0,0 +1,4 @@
+Changelog
+=========
+
+.. include:: ../CHANGES.rst

docs/conf.py

@@ -40,9 +40,7 @@ release = '1.0.0'
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.coverage',
-    'sphinx_autodoc_typehints'
+    'sphinx.ext.intersphinx'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -84,7 +82,17 @@ html_theme = 'alabaster'
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'github_user': 'icetemple',
+    'github_repo': 'genrss',
+    'canonical_url': 'https://genrss.readthedocs.io/en/latest/',
+    'description': 'RSS generator for python',
+    'fixed_sidebar': True,
+    'github_banner': True,
+    'github_button': True,
+    'travis_button': True,
+}
+
 
 # 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,
@@ -99,7 +107,13 @@ html_static_path = ['_static']
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
-# html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'about.html',
+        'localtoc.html',
+        'navigations.html',
+    ]
+}
 
 
 # -- Options for HTMLHelp output ---------------------------------------------

docs/index.rst

@@ -1,22 +1,46 @@
-.. GenRSS documentation master file, created by
-   sphinx-quickstart on Wed Jul 24 11:05:33 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. rst-class: hide-header
 
-Welcome to GenRSS's documentation!
-==================================
+Welcome to GenRSS!
+==================
 
-.. automodule:: genrss
-   :members:
+This is generator of rss feed for your channel. Easy for config and usage.
+
+Get started with :ref:`installation` and then get an overview with
+the :ref:`quickstart`. The rest of the docs describe each component
+of GenRSS in detail, with a full reference in the :ref:`api` section.
+
+
+User's Guide
+------------
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+
+   installation
+   quickstart
 
 
-Indices and tables
-==================
+API Reference
+-------------
+
+If you are looking for information on a specific function, class or
+method, this part of the documentation is for you.
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+
+
+Additional notes
+----------------
+
+legal information and changelog are here for the interested.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   changelogs
+
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/installation.rst

@@ -0,0 +1,37 @@
+.. _installation:
+
+Installation
+============
+
+Python Version
+--------------
+
+We recommend using the latest version of Python 3. GenRSS supports
+Python 3.6 and newer.
+
+
+Dependencies
+------------
+
+These distributions will be installed automatically when installing GenRSS.
+
+* ``lxml==4.3.4``
+* ``pytz==2019.1``
+
+
+Install GenRSS
+--------------
+
+Use the following command to install GenRSS:
+
+``pip install genrss``
+
+GenRSS is now installed. Check out :ref:`quickstart`
+
+Install from source
+-------------------
+
+If you want to work with the latest GenRSS code before it’s released,
+install or update the code from the master branch:
+
+``pip install -U https://github.com/icetemple/genrss/archive/master.zip``

docs/quickstart.rst

@@ -0,0 +1,42 @@
+.. _quickstart:
+
+Quickstart
+==========
+
+Do you want to get started? This page gives a good introduction to GetRSS.
+It assumes you already have GenRSS installed. If you do not, head over
+to the :ref:`installation` section.
+
+
+A Simple Example
+----------------
+.. code-block:: python
+
+    from datetime import datetime
+    from genrss import GenRSS
+
+    feed = GenRSS(title='SmartFridge',
+                  site_url='https://smartfridge.me',
+                  feed_url='https://smartfridge.me/feed/rss.xml')
+
+    feed.item(title='black buns for burgers',
+              description='For the first time black burgers appeared ' \
+                          'in Japan. Unusual dark color buns complemented ' \
+                          'with black cheese and sauce. Over time, the dish ' \
+                          'has conquered the whole world. The main secret ' \
+                          'ingredient in popular buns is the most common... ' \
+                          'charcoal!',
+              url='https://smartfridge.me/recipe/316b28-chernye-bulochki-dlya-burgerov/',
+              author='@smartfridge',
+              categories=['baking'],
+              pub_date=datetime.utcnow())
+
+    xml = feed.xml()
+
+..
+
+This code initializes small feed about recipe site with one item and returns
+xml as string
+
+
+For more information about GenRSS you can have a look :ref:`api` section.

setup.py

@@ -8,7 +8,7 @@ with open('README.md', 'r') as f:
 if __name__ == '__main__':
     setup(
         name='genrss',
-        version='1.0.1',
+        version='1.0.2',
         author='Dmitriy Pleshevskiy',
         author_email='dmitriy@ideascup.me',
         description='RSS feed generator for python',