diff --git a/.gitignore b/.gitignore index 3c6c11b..e55f7e6 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ /build/ /deb_dist/ /dist/ +/docs/_build/ /htmlcov/ /tmp/ -/toot-*.tar.gz +/toot-*.tar.gz \ No newline at end of file diff --git a/RELEASE.md b/RELEASE.md deleted file mode 100644 index be7d0ef..0000000 --- a/RELEASE.md +++ /dev/null @@ -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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..57ed83d --- /dev/null +++ b/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) diff --git a/docs/_static/curses.png b/docs/_static/curses.png new file mode 100644 index 0000000..5392d94 Binary files /dev/null and b/docs/_static/curses.png differ diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..9c7a5b3 --- /dev/null +++ b/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; +} diff --git a/docs/_static/trumpet.png b/docs/_static/trumpet.png new file mode 100644 index 0000000..03233ae Binary files /dev/null and b/docs/_static/trumpet.png differ diff --git a/docs/_templates/about.html b/docs/_templates/about.html new file mode 100644 index 0000000..2119d71 --- /dev/null +++ b/docs/_templates/about.html @@ -0,0 +1,5 @@ +

{{ project }}

+ +{% if theme_description %} +

{{ theme_description }}

+{% endif %} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..f610945 --- /dev/null +++ b/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", + ] +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..1680254 --- /dev/null +++ b/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 + +Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..0eba7fe --- /dev/null +++ b/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 `_. + + +APT package repository +---------------------- + +This works for Debian, Ubuntu and derivatives. The repo is signed with my +`keybase.io `_ 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 `_ + +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 `_ + +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 `_. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..5d625a1 --- /dev/null +++ b/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 diff --git a/docs/release.rst b/docs/release.rst new file mode 100644 index 0000000..9a2fba3 --- /dev/null +++ b/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 `_. + +* 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 `_ 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) diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..5fca6cf --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,81 @@ +===== +Usage +===== + +Running ``toot`` displays a list of available commands. + +Running ``toot -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 --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. diff --git a/requirements-dev.txt b/requirements-dev.txt index e532287..9d22a05 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -2,6 +2,8 @@ keyring pytest pytest-cov pyxdg +sphinx +sphinx-autobuild stdeb twine wheel