From b9fd3bf98b6b150e431a01ca2aad97672d3de54a Mon Sep 17 00:00:00 2001 From: Ivan Habunek Date: Wed, 27 Jun 2018 16:23:03 +0200 Subject: [PATCH] Replace docs in README with link rtfd.io --- README.rst | 184 +++++-------------------------------------------- docs/index.rst | 18 +++-- docs/usage.rst | 56 ++++++++++----- 3 files changed, 69 insertions(+), 189 deletions(-) diff --git a/README.rst b/README.rst index e9a1ed4..e3248f8 100644 --- a/README.rst +++ b/README.rst @@ -15,182 +15,32 @@ Interact with Mastodon social network from the command line. .. image:: https://img.shields.io/pypi/v/toot.svg?maxAge=3600&style=flat-square :target: https://pypi.python.org/pypi/toot -Installation ------------- +Documentation +------------- -Debian Buster -~~~~~~~~~~~~~ +Documentation is hosted on readthedocs.io. Check it out for instruction on installation, usage and more. -If you're running Debian Buster (testing), toot is available in the Debian -package repository. +https://toot.readthedocs.io/en/latest/ -.. code-block:: +Features +-------- - sudo apt install toot +* 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 -Debian package is maintained by `Jonathan Carter `_. +Curses UI +--------- +toot has an experimental curses based console UI. -From 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:: - - 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:: - - sudo apt update - sudo apt install python3-toot - -From FreeBSD ports -~~~~~~~~~~~~~~~~~~ - -Install the package: - -.. code-block:: - - pkg install py36-toot - -Build and install from sources: - -.. code-block:: - - cd /usr/ports/net-im/toot - make install - -FreeBSD port is maintained by `Mateusz Piotrowski `_ - -From Nixpkgs -~~~~~~~~~~~~ - -This works on NixOS or systems with the Nix package manager installed. - -.. code-block:: - - nix-env -iA nixos.toot - - -From OpenBSD ports -~~~~~~~~~~~~~~~~~~ - -Install the package: - -.. code-block:: - - pkg_add toot - -Build and install from sources: - -.. code-block:: - - cd /usr/ports/net/toot - make install - -OpenBSD port is maintained by `Klemens Nanni `_ - -From Python Package Index -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Otherwise, install from PyPI using pip, preferably into a virtual environment: - -.. code-block:: - - pip install toot - -Usage ------ - -Running ``toot`` displays a list of available commands. - -Running ``toot -h`` shows the documentation for the given command. - -.. code-block:: - - $ 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:: - - echo "Text to post" | toot post - cat mypost.txt | toot post - - -Authentication --------------- - -Before tooting, you need to login to a Mastodon instance. - -.. code-block:: - - 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:: - - 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. +.. image :: https://raw.githubusercontent.com/ihabunek/toot/master/docs/_static/curses.png License ------- -Copyright 2017 Ivan Habunek +Copyright 2018 Ivan Habunek -Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html +Licensed under `GPLv3 `_, see `LICENSE `_. diff --git a/docs/index.rst b/docs/index.rst index 1680254..75161f2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,17 @@ toot - Mastodon CLI client toot is a commandline tool for interacting with Mastodon social networks. -Contents: +.. image:: https://img.shields.io/travis/ihabunek/toot.svg?maxAge=3600&style=flat-square + :target: https://travis-ci.org/ihabunek/toot +.. image:: https://img.shields.io/badge/author-%40ihabunek-blue.svg?maxAge=3600&style=flat-square + :target: https://mastodon.social/@ihabunek +.. image:: https://img.shields.io/github/license/ihabunek/toot.svg?maxAge=3600&style=flat-square + :target: https://opensource.org/licenses/MIT +.. image:: https://img.shields.io/pypi/v/toot.svg?maxAge=3600&style=flat-square + :target: https://pypi.python.org/pypi/toot + +Contents +-------- .. toctree:: :maxdepth: 1 @@ -26,7 +36,7 @@ Features Curses UI --------- -toot has an experimental curses based console UI. +toot has an experimental curses based console UI. Run it with ``toot curses``. .. image :: _static/curses.png @@ -42,6 +52,6 @@ Please report any issues there. Pull requests are welcome. License ------- -Copyright 2017 Ivan Habunek +Copyright 2018 Ivan Habunek -Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html +Licensed under `GPLv3 `_. diff --git a/docs/usage.rst b/docs/usage.rst index 5fca6cf..b958bbc 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -45,18 +45,10 @@ Running ``toot -h`` shows the documentation for the given command. 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. +Before tooting, you need to log into a Mastodon instance. .. code-block:: sh @@ -64,18 +56,46 @@ Before tooting, you need to login to a Mastodon instance. 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. +Using multiple accounts +~~~~~~~~~~~~~~~~~~~~~~~ + +It's possible to be logged into **multiple accounts** at the same time. Just repeat the login 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. + +Examples +-------- + +Posting +~~~~~~~ + +The simplest action is posting a status. + +.. code-block:: bash + + toot post "hello there" + +You can also attach media: + +.. code-block:: bash + + toot post "hello media" --media path/to/image.png + +If the media is sensitive, mark it as such and people will need to click to show it: + +.. code-block:: bash + + toot post "naughty pics ahoy" --media nsfw.png --sensitive + + +It is possible to pipe in the status text: + +.. code-block:: bash + + echo "Text to post" | toot post + cat post.txt | toot post + toot post < post.txt