From e78a98e85c18efe43ddc9bc8c2c9160ee76100d1 Mon Sep 17 00:00:00 2001 From: Dmitriy Pleshevskiy Date: Wed, 24 Jul 2019 23:16:19 +0300 Subject: [PATCH] fead: add documentation pages and readme.md --- CHANGES.rst | 8 +++++ Pipfile.lock | 7 +++-- README.md | 37 +++++++++++++++++++++++ docs/.nojekyll | 0 docs/Makefile | 4 --- docs/_templates/localtoc.html | 2 ++ docs/_templates/navigations.html | 13 ++++++++ docs/api.rst | 9 ++++++ docs/changelogs.rst | 4 +++ docs/conf.py | 24 ++++++++++++--- docs/index.rst | 52 +++++++++++++++++++++++--------- docs/installation.rst | 37 +++++++++++++++++++++++ docs/quickstart.rst | 42 ++++++++++++++++++++++++++ setup.py | 2 +- 14 files changed, 214 insertions(+), 27 deletions(-) create mode 100644 CHANGES.rst delete mode 100644 docs/.nojekyll create mode 100644 docs/_templates/localtoc.html create mode 100644 docs/_templates/navigations.html create mode 100644 docs/api.rst create mode 100644 docs/changelogs.rst create mode 100644 docs/installation.rst create mode 100644 docs/quickstart.rst diff --git a/CHANGES.rst b/CHANGES.rst new file mode 100644 index 0000000..2623543 --- /dev/null +++ b/CHANGES.rst @@ -0,0 +1,8 @@ +.. currentmodule:: genrss + +Version 1.0.0 +------------- + +Released 2019-07-23 + +- First public preview release. \ No newline at end of file diff --git a/Pipfile.lock b/Pipfile.lock index 92dc0a2..e372ee7 100644 --- a/Pipfile.lock +++ b/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": { diff --git a/README.md b/README.md index 1ada341..1130b9c 100644 --- a/README.md +++ b/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/) diff --git a/docs/.nojekyll b/docs/.nojekyll deleted file mode 100644 index e69de29..0000000 diff --git a/docs/Makefile b/docs/Makefile index 225fe6c..298ea9e 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/_templates/localtoc.html b/docs/_templates/localtoc.html new file mode 100644 index 0000000..76cca65 --- /dev/null +++ b/docs/_templates/localtoc.html @@ -0,0 +1,2 @@ +

Contents

+{{ toc }} diff --git a/docs/_templates/navigations.html b/docs/_templates/navigations.html new file mode 100644 index 0000000..0686ece --- /dev/null +++ b/docs/_templates/navigations.html @@ -0,0 +1,13 @@ +

Navigation

+ \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..120da92 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,9 @@ +.. _api: + +API +=== + +.. automodule:: genrss + +.. autoclass:: GenRSS + :members: \ No newline at end of file diff --git a/docs/changelogs.rst b/docs/changelogs.rst new file mode 100644 index 0000000..218fe33 --- /dev/null +++ b/docs/changelogs.rst @@ -0,0 +1,4 @@ +Changelog +========= + +.. include:: ../CHANGES.rst diff --git a/docs/conf.py b/docs/conf.py index a6286a8..bad5715 100644 --- a/docs/conf.py +++ b/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 --------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 5c472f1..8883e72 100644 --- a/docs/index.rst +++ b/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` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..2f6b129 --- /dev/null +++ b/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`` diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..ad0e05e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/setup.py b/setup.py index 7b9b722..4bad286 100644 --- a/setup.py +++ b/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',