Add sphinx docs

.gitignore

@@ -9,6 +9,7 @@
 /build/
 /deb_dist/
 /dist/
+/docs/_build/
 /htmlcov/
 /tmp/
-/toot-*.tar.gz
+/toot-*.tar.gz

RELEASE.md

@@ -1,32 +0,0 @@
-Release instructions
-====================
-
-* Update the version number in `setup.py`
-* Update the version number in `toot/__init__.py`
-* Update the `CHANGELOG.md` with the release notes & date
-* Tag a release
-* Push master & tag to GitHub
-
-Github release
---------------
-
-* Create a release for new tag, paste changelog since last tag in description
-* Download assets generated by github (.zip and .tar.gz) and upload them to the relase
-* Also upload the generated .deb file
-
-Publishing to PyPI
-------------------
-
-* `make dist` to create source and wheel distributions
-* `make publish` to push them to PyPI
-
-Publishing to Debian repo
--------------------------
-
-Publishing deb packages is done via [ihabunek/packages](https://github.com/ihabunek/packages)
-
-* `make deb` to create the debian package
-* copy deb file to packages project directory
-* in packages project directory:
-    * `make` to build the repo files
-    * `make publish` to send them to the server

docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = toot
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+serve:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,10 @@
+pre {
+    padding: 8px 15px;
+}
+
+div.contents {
+    background-color: inherit;
+    border: 0;
+    margin-top: 0;
+    padding-top: 0;
+}

docs/_templates/about.html

@@ -0,0 +1,5 @@
+<h1 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }}</a></h1>
+
+{% if theme_description %}
+    <p class="blurb">{{ theme_description }}</p>
+{% endif %}

docs/conf.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+
+from datetime import datetime
+
+# -- Project information -----------------------------------------------------
+
+project = 'toot'
+year = datetime.now().year
+copyright = '{}, Ivan Habunek'.format(year)
+author = 'Ivan Habunek'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = []
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'alabaster'
+html_theme_options = {
+    "description": "Mastodon CLI client",
+    "github_user": "ihabunek",
+    "github_repo": "toot",
+    "fixed_sidebar": True,
+    "travis_button": True,
+    "logo": 'trumpet.png',
+}
+html_static_path = ['_static']
+html_sidebars = {
+    "**": [
+        "about.html",
+        "navigation.html",
+        "relations.html",
+        "searchbox.html",
+    ]
+}

docs/index.rst

@@ -0,0 +1,47 @@
+toot - Mastodon CLI client
+==========================
+
+.. image:: _static/trumpet.png
+
+toot is a commandline tool for interacting with Mastodon social networks.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   install
+   usage
+   release
+
+Features
+--------
+
+* Posting, replying, deleting statuses
+* Support for media uploads, spoiler text, sensitive content
+* Search by account or hash tag
+* Following, muting and blocking accounts
+* Simple swithcing between authenticated in Mastodon accounts
+
+Curses UI
+---------
+
+toot has an experimental curses based console UI.
+
+.. image :: _static/curses.png
+
+Development
+-----------
+
+The project source code and issue tracker are available on GitHub:
+
+https://github.com/ihabunek/toot
+
+Please report any issues there. Pull requests are welcome.
+
+License
+-------
+
+Copyright 2017 Ivan Habunek <ivan@habunek.com>
+
+Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html

docs/install.rst

@@ -0,0 +1,102 @@
+============
+Installation
+============
+
+toot is packaged for various platforms.
+
+.. contents::
+    :local:
+    :backlinks: none
+
+Debian Buster
+-------------
+
+If you're running Debian Buster (testing), toot is available in the Debian package repository.
+
+.. code-block:: bash
+
+    sudo apt install toot
+
+Debian package is maintained by `Jonathan Carter <https://mastodon.xyz/@highvoltage>`_.
+
+
+APT package repository
+----------------------
+
+This works for Debian, Ubuntu and derivatives. The repo is signed with my
+`keybase.io <https://keybase.io/ihabunek>`_ key.
+
+Add the `bezdomni.net` repository:
+
+.. code-block:: bash
+
+    echo "deb http://bezdomni.net/packages/ ./" | sudo tee /etc/apt/sources.list.d/bezdomni.list
+    curl https://keybase.io/ihabunek/pgp_keys.asc | sudo apt-key add -
+
+Install the package:
+
+.. code-block:: bash
+
+    sudo apt update
+    sudo apt install python3-toot
+
+FreeBSD ports
+-------------
+
+Install the package:
+
+.. code-block:: bash
+
+    pkg install py36-toot
+
+Build and install from sources:
+
+.. code-block:: bash
+
+    cd /usr/ports/net-im/toot
+    make install
+
+FreeBSD port is maintained by `Mateusz Piotrowski <https://mastodon.social/@mpts>`_
+
+Nixpkgs
+-------
+
+This works on NixOS or systems with the Nix package manager installed.
+
+.. code-block:: bash
+
+    nix-env -iA nixos.toot
+
+
+OpenBSD ports
+-------------
+
+Install the package:
+
+.. code-block:: bash
+
+    pkg_add toot
+
+Build and install from sources:
+
+.. code-block:: bash
+
+    cd /usr/ports/net/toot
+    make install
+
+OpenBSD port is maintained by `Klemens Nanni <mailto:kl3@posteo.org>`_
+
+Python Package Index
+--------------------
+
+Install from PyPI using pip, preferably into a virtual environment:
+
+.. code-block:: bash
+
+    pip install toot
+
+Source
+------
+
+Finally, you can get the latest source distribution, wheel or debian package
+`from Github <https://github.com/ihabunek/toot/releases/latest/>`_.

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=toot
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/release.rst

@@ -0,0 +1,43 @@
+=================
+Release procedure
+=================
+
+This document is a checklist for creating a toot release.
+
+Currently the process is pretty manual and would benefit from automatization.
+
+Bump & tag version
+------------------
+
+* Update the version number in ``setup.py``
+* Update the version number in ``toot/__init__.py``
+* Update the ``CHANGELOG.md`` with the release notes & date
+* Tag a release in git
+* Push master & tag to GitHub
+
+Publishing to PyPI
+------------------
+
+* ``make dist`` to create source and wheel distributions
+* ``make publish`` to push them to PyPI
+
+Publishing to Debian repo
+-------------------------
+
+Publishing deb packages is done via `ihabunek/packages <https://github.com/ihabunek/packages>`_.
+
+* run ``make deb`` to create the debian package
+* copy deb file to packages project directory
+* in packages project directory:
+    * ``make`` to build the repo files
+    * ``make publish`` to send them to the server
+
+Github release
+--------------
+
+* `Create a release <https://github.com/ihabunek/toot/releases/>`_ for the newly
+  pushed tag, paste changelog since last tag in the description
+* Upload the assets generated in previous two steps to the release:
+    * source dist (.zip and .tar.gz)
+    * wheel distribution (.whl)
+    * debian package (.deb)

docs/usage.rst

@@ -0,0 +1,81 @@
+=====
+Usage
+=====
+
+Running ``toot`` displays a list of available commands.
+
+Running ``toot <command> -h`` shows the documentation for the given command.
+
+.. code-block:: none
+
+    $ toot
+
+    toot - a Mastodon CLI client
+
+    Authentication:
+      toot login       Log into a mastodon instance using your browser (recommended)
+      toot login_cli   Log in from the console, does NOT support two factor authentication
+      toot activate    Switch between logged in accounts.
+      toot logout      Log out, delete stored access keys
+      toot auth        Show logged in accounts and instances
+
+    Read:
+      toot whoami      Display logged in user details
+      toot whois       Display account details
+      toot instance    Display instance details
+      toot search      Search for users or hashtags
+      toot timeline    Show recent items in a timeline (home by default)
+      toot curses      An experimental timeline app (doesn't work on Windows)
+
+    Post:
+      toot post        Post a status text to your timeline
+      toot upload      Upload an image or video file
+      toot delete      Delete an existing status
+
+    Accounts:
+      toot follow      Follow an account
+      toot unfollow    Unfollow an account
+      toot mute        Mute an account
+      toot unmute      Unmute an account
+      toot block       Block an account
+      toot unblock     Unblock an account
+
+    To get help for each command run:
+      toot <command> --help
+
+    https://github.com/ihabunek/toot
+
+It is possible to pipe status text into `toot post`, for example:
+
+.. code-block:: sh
+
+    echo "Text to post" | toot post
+    cat mypost.txt | toot post
+
+
+Authentication
+--------------
+
+Before tooting, you need to login to a Mastodon instance.
+
+.. code-block:: sh
+
+    toot login
+
+You will be redirected to your Mastodon instance to log in and authorize toot to access your account, and will be given an **authorization code** in return which you need to enter to log in.
+
+If you don't use two factor authentication you can also log in directly from the command line:
+
+.. code-block:: sh
+
+    toot login_cli
+
+You will be asked to chose an instance and enter your credentials.
+
+The application and user access tokens will be saved in the configuration file located at ``~/.config/toot/instances/config.json``.
+
+It's possible to be logged into **multiple accounts** at the same time. Just repeat the above process for another instance. You can see all logged in accounts by running ``toot auth``. The currently active account will have an **ACTIVE** flag next to it.
+
+To switch accounts, use ``toot activate``. Alternatively, most commands accept a ``--using`` option which can be used to specify the account you wish to use just that one time.
+
+Finally you can logout from an account by using ``toot logout``. This will remove the stored access tokens for that account.

requirements-dev.txt

@@ -2,6 +2,8 @@ keyring
 pytest
 pytest-cov
 pyxdg
+sphinx
+sphinx-autobuild
 stdeb
 twine
 wheel