Merge branch 'docs'

buckket · Feb 16, 2016 · 91e7640 · 91e7640
2 parents c3d0139 + ee46d87
commit 91e7640
Show file tree

Hide file tree

Showing 11 changed files with 152 additions and 90 deletions.
diff --git a/docs/_static/style.css b/docs/_static/style.css
@@ -0,0 +1,12 @@
+@import url("alabaster.css");
+
+
+div.sphinxsidebar #searchbox input[type="text"] {
+    width: 142px;
+}
+
+div.sphinxsidebarwrapper p.logo {
+    margin: -10px 0 10px 0;
+    text-align: center;
+    width: 75%;
+}
diff --git a/docs/_static/twtxt.svg b/docs/_static/twtxt.svg
diff --git a/docs/api.rst b/docs/api.rst
@@ -7,37 +7,17 @@ API
 
 This chapter documents twtxts API and source code internals.
 
-Tweet Class
------------
+Models
+------
 
 .. autoclass:: models.Tweet
    :members:
 
-   .. attribute:: text
-
-      A :class:`str` representing the message of the tweet.
-
-   .. attribute:: created_at
-
-      A :class:`datetime` representing the creation date of the tweet.
-      A value in the future results in an error log.
-
-
-Source Class
-------------
-
 .. autoclass:: models.Source
    :members:
 
-   .. attribute:: nick
+Config
+------
 
-      A :class:`str` representing the nick name of the Source.
-
-   .. attribute:: url
-
-      A :class:`str` representing the URL to the sources twtxt file (feed URL).
-
-   .. attribute:: file
-
-      A :class:`str` representing a path to the local twtxt file if available.
-      This is attribute is only needed for the users own feed.
+.. autoclass:: config.Config
+   :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,9 +12,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
-import shlex
+import sys
+
+import alabaster
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -31,8 +32,9 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
     'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'alabaster',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -59,9 +61,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.1.0'
+version = '1.2.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.1.0'
+release = '1.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -117,10 +119,20 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'logo': 'twtxt.svg',
+    'description': 'twtxt is a decentralised, minimalist microblogging service for hackers.',
+    'github_user': 'buckket',
+    'github_repo': 'twtxt',
+    'github_banner': True,
+    'extra_nav_links': {
+        'twtxt @ PyPI': 'https://pypi.python.org/pypi/twtxt',
+        'Issue Tracker': 'https://github.com/buckket/twtxt/issues',
+    },
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = [alabaster.get_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -154,10 +166,17 @@
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
-#html_use_smartypants = True
+html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',
+        'searchbox.html',
+    ],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -173,13 +192,13 @@
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -286,3 +305,11 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# Customize CSS by loading our own first
+html_style = 'style.css'
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3.4', None),
+    'click': ('http://click.pocoo.org/5/', None),
+}
diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -3,32 +3,35 @@
 Configuration
 =============
 
-twtxt uses a simple INI-like configuration file. It’s recommended to use ``twtxt quickstart`` to create it. On Linux twtxt checks ``~/.config/twtxt/config`` for its configuration. OSX uses ``~/Library/Application Support/twtxt/config``. Consult `get_app_dir <http://click.pocoo.org/6/api/#click.get_app_dir>`_ to find out the config directory for other operating systems.
+twtxt uses a simple INI-like configuration file. It’s recommended to use ``twtxt quickstart`` to create it. On Linux twtxt checks ``~/.config/twtxt/config`` for its configuration. OSX uses ``~/Library/Application Support/twtxt/config``. Consult :func:`click.get_app_dir` to find out the config directory for other operating systems.
 
 Here’s an example ``conf`` file, showing every currently supported option:
 
-.. code::
+.. code-block:: ini
 
     [twtxt]
     nick = buckket
     twtfile = ~/twtxt.txt
     twturl = http://example.org/twtxt.txt
     check_following = True
     use_pager = False
+    use_cache = True
     porcelain = False
+    disclose_identity = False
     limit_timeline = 20
     timeout = 5.0
     sorting = descending
+    pre_tweet_hook = "scp buckket@example.org:~/public_html/twtxt.txt {twtfile}"
     post_tweet_hook = "scp {twtfile} buckket@example.org:~/public_html/twtxt.txt"
-    # post_tweet_hook = "aws s3 {twtfile} s3://mybucket.org/twtxt.txt --acl public-read --storage-class REDUCED_REDUNDANCY --cache-control 'max-age=60,public'"
+    # post_tweet_hook = "tail -1 {twtfile} | cut -f2 | sed -e 's/^/twt=/'| curl -s -d @- -d 'name=foo' -d 'password=bar' http://htwtxt.plomlompom.com/feeds"
+    # post_tweet_hook = "aws s3 cp {twtfile} s3://mybucket.org/twtxt.txt --acl public-read --storage-class REDUCED_REDUNDANCY --cache-control 'max-age=60,public'"
 
     [following]
     bob = https://example.org/bob.txt
     alice = https://example.org/alice.txt
 
-
-[twtxt] section
----------------
+[twtxt]
+-------
 
 +-------------------+-------+------------+---------------------------------------------------+
 | Option:           | Type: | Default:   | Help:                                             |
@@ -43,20 +46,25 @@ Here’s an example ``conf`` file, showing every currently supported option:
 +-------------------+-------+------------+---------------------------------------------------+
 | use_pager         | BOOL  | False      | use a pager (less) to display your timeline       |
 +-------------------+-------+------------+---------------------------------------------------+
+| use_cache         | BOOL  | True       | cache remote twtxt files locally                  |
++-------------------+-------+------------+---------------------------------------------------+
 | porcelain         | BOOL  | False      | style output in an easy-to-parse format           |
 +-------------------+-------+------------+---------------------------------------------------+
+| disclose_identity | BOOL  | False      | include nick and twturl in twtxt’s user-agent     |
++-------------------+-------+------------+---------------------------------------------------+
 | limit_timeline    | INT   | 20         | limit amount of tweets shown in your timeline     |
 +-------------------+-------+------------+---------------------------------------------------+
 | timeout           | FLOAT | 5.0        | maximal time a http request is allowed to take    |
 +-------------------+-------+------------+---------------------------------------------------+
 | sorting           | TEXT  | descending | sort timeline either descending or ascending      |
 +-------------------+-------+------------+---------------------------------------------------+
+| pre_tweet_hook    | TEXT  |            | command to be executed before tweeting            |
++-------------------+-------+------------+---------------------------------------------------+
 | post_tweet_hook   | TEXT  |            | command to be executed after tweeting             |
 +-------------------+-------+------------+---------------------------------------------------+
 
-``post_tweet_hook`` is very useful if you want to push your twtxt file to a remote (web) server. Check the example above tho see how it’s used with ``scp``.
-
-[followings] section
---------------------
+``pre_tweet_hook`` and ``post_tweet_hook`` are very useful if you want to push your twtxt file to a remote (web) server. Check the example above tho see how it’s used with ``scp``.
 
-This section holds all your followings as nick, URL pairs. You can edit this section manually or use the ``follow``/``unfollow`` commands of twtxt for greater comfort.
+[followings]
+------------
+This section holds all your followings as nick, URL pairs. You can edit this section manually or use the ``follow``/``unfollow`` commands of twtxt for greater comfort.
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,15 +1,18 @@
 Welcome to twtxt!
 =================
 
-Welcome to twtxt's documentation. This documentation is divided into multiple parts.
+Current release: v\ |version|.
+
+Welcome to twtxt’s documentation. This documentation is divided into multiple parts.
 We recommend you to get started with the :ref:`installation` and then head over to the
-:ref:`quickstart` section. There is a more detailed :ref:`usage` section about how to use
-twtxt from the CLI. The internals of twtxt are documented in the :ref:`api` chapter.
+:ref:`quickstart` section. If you don’t know what this is about read the :ref:`intro` first.
+There is a more detailed :ref:`usage` section about how to use twtxt via the CLI.
+The internals of twtxt are documented in the :ref:`api` chapter.
 
-Feel free to contribute to this project. The source code is maintained on `Github`_.
+Feel free to contribute to this project. The source code is maintained on `GitHub`_.
 
-User's Guide
-------------
+User Guide
+----------
 
 .. toctree::
    :maxdepth: 2
@@ -22,16 +25,23 @@ User's Guide
    twtxtfile
    registry
 
+Community
+---------
+
+- twtxt IRC channel: **#twtxt** on `irc.freenode.net`_
 
 API Reference
 -------------
 
-This part of the documentation describes the modules, classes, functions and other source code specific details.
+This part of the documentation describes the modules, classes, functions and other source code specific details of twtxt.
 
 .. toctree::
    :maxdepth: 2
 
    api
 
 
-.. _Github: https://github.com/buckket/twtxt
+
+
+.. _GitHub: https://github.com/buckket/twtxt
+.. _irc.freenode.net: https://freenode.net/
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -3,43 +3,51 @@
 Installation
 ============
 
-The following sections describe how to install twtxt in different ways on your machine.
+The following sections describe how to install twtxt in different ways on your machine. Currently the we support Windows, Mac OS X and Linux via pip_.
 
-Requirements:
+**Requirements**:
 
-- Python version > **3.4.1**
-- Installed version of pip
+- Python_ >= **3.4.1**
+- Recent version of pip_
 
 Release version
 ---------------
 
-Install twtxt using pip:
+Install twtxt using pip_:
 
-.. code::
+.. code-block:: console
 
     $ pip3 install twtxt
 
-*Tip*: Instead of installing the package globally (as root), you may want to install this package locally by passing ``--user`` to pip, make sure that you include ``~/.local/bin/`` in your ``$PATH``. Using pyvenv and running twtxt from within a virtualenv is also an option!
+.. note::
+
+    Instead of installing the package globally (as root), you may want to install this package locally by passing ``--user`` to pip,
+    make sure that you append ``~/.local/bin/`` to your ``$PATH``. Using pyvenv and running twtxt from within a virtualenv is also an option!
 
 Development version
 -------------------
 
-Clone the git repository:
+Clone the git_ repository:
 
-.. code::
+.. code-block:: console
 
     $ git clone https://github.com/buckket/twtxt.git
 
 We recommend you to develop inside a virtualenv:
 
-.. code::
+.. code-block:: console
 
-    $ virtualenv env -p python3.4
-    ...
+    $ pyvenv env
+        ...
     $ source env/bin/activate
 
-Install the package via pip in developer mode:
+Install the package via pip_ in developer mode:
 
-.. code::
+.. code-block:: console
 
     $ pip3 install -e twtxt/
+
+
+.. _Python: https://www.python.org/
+.. _pip: http://pip-installer.org/
+.. _git: https://git-scm.com/
diff --git a/docs/intro.rst b/docs/intro.rst
@@ -5,12 +5,22 @@ Introduction
 
 **twtxt** is a decentralised, minimalist microblogging service for hackers.
 
-So you want to get some thoughts out on the internet in a convenient and slick way while also following the gibberish of others? Instead of signing up at a closed and/or regulated microblogging platform, getting your status updates out with twtxt is as easy as putting them in a publicly accessible text file. The URL pointing to this file is your identity, your account. twtxt then tracks these text files, like a feedreader, and builds your unique timeline out of them, depending on which files you track. The format is simple, human readable, and integrates well with UNIX command line utilities.
-
-|demo|
+You want to get some thoughts out on the internet in a convenient and slick way while also following the gibberish of others? Instead of signing up at a closed and/or regulated microblogging platform, getting your status updates out with twtxt is as easy as putting them in a publicly accessible text file. The URL pointing to this file is your identity, your account. twtxt then tracks these text files, like a feedreader, and builds your unique timeline out of them, depending on which files you track. The format is simple, human readable, and integrates well with UNIX command line utilities.
 
 **tl;dr**: twtxt is a CLI tool, as well as a format specification for self-hosted flat file based microblogging.
 
+Demonstration
+-------------
+
+|demo|
+
 .. |demo| image:: https://asciinema.org/a/1w2q3suhgrzh2hgltddvk9ot4.png
     :target: https://asciinema.org/a/1w2q3suhgrzh2hgltddvk9ot4
     :alt: Demo
+
+Features
+--------
+- A beautiful command-line interface thanks to click.
+- Asynchronous HTTP requests thanks to asyncio/aiohttp and Python 3.
+- Integrates well with existing tools (scp, cut, echo, date, etc.) and your shell.
+- Don’t like the official client? Tweet using ``echo -e "`date -Im`\tHello world!" >> twtxt.txt``!
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -5,7 +5,7 @@ Quickstart
 
 Use twtxt's **quickstart** command to bootstrap a default configuration:
 
-.. code::
+.. code-block:: console
 
     $ twtxt quickstart