mirror of
https://github.com/ihabunek/toot.git
synced 2025-01-03 14:56:37 -05:00
Add sphinx docs
This commit is contained in:
parent
1af645757e
commit
acfe686c09
1
.gitignore
vendored
1
.gitignore
vendored
@ -9,6 +9,7 @@
|
|||||||
/build/
|
/build/
|
||||||
/deb_dist/
|
/deb_dist/
|
||||||
/dist/
|
/dist/
|
||||||
|
/docs/_build/
|
||||||
/htmlcov/
|
/htmlcov/
|
||||||
/tmp/
|
/tmp/
|
||||||
/toot-*.tar.gz
|
/toot-*.tar.gz
|
32
RELEASE.md
32
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
|
|
23
docs/Makefile
Normal file
23
docs/Makefile
Normal file
@ -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)
|
BIN
docs/_static/curses.png
vendored
Normal file
BIN
docs/_static/curses.png
vendored
Normal file
Binary file not shown.
After (image error) Size: 82 KiB |
10
docs/_static/custom.css
vendored
Normal file
10
docs/_static/custom.css
vendored
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
pre {
|
||||||
|
padding: 8px 15px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.contents {
|
||||||
|
background-color: inherit;
|
||||||
|
border: 0;
|
||||||
|
margin-top: 0;
|
||||||
|
padding-top: 0;
|
||||||
|
}
|
BIN
docs/_static/trumpet.png
vendored
Normal file
BIN
docs/_static/trumpet.png
vendored
Normal file
Binary file not shown.
After (image error) Size: 16 KiB |
5
docs/_templates/about.html
vendored
Normal file
5
docs/_templates/about.html
vendored
Normal file
@ -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 %}
|
40
docs/conf.py
Normal file
40
docs/conf.py
Normal file
@ -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",
|
||||||
|
]
|
||||||
|
}
|
47
docs/index.rst
Normal file
47
docs/index.rst
Normal file
@ -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
|
102
docs/install.rst
Normal file
102
docs/install.rst
Normal file
@ -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/>`_.
|
36
docs/make.bat
Normal file
36
docs/make.bat
Normal file
@ -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
|
43
docs/release.rst
Normal file
43
docs/release.rst
Normal file
@ -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)
|
81
docs/usage.rst
Normal file
81
docs/usage.rst
Normal file
@ -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.
|
@ -2,6 +2,8 @@ keyring
|
|||||||
pytest
|
pytest
|
||||||
pytest-cov
|
pytest-cov
|
||||||
pyxdg
|
pyxdg
|
||||||
|
sphinx
|
||||||
|
sphinx-autobuild
|
||||||
stdeb
|
stdeb
|
||||||
twine
|
twine
|
||||||
wheel
|
wheel
|
||||||
|
Loading…
Reference in New Issue
Block a user