Add sphinx docs
This commit is contained in:
Ivan Habunek
parent
1af645757e
commit
acfe686c09
|
|
@ -9,6 +9,7 @@
|
|||
/build/
|
||||
/deb_dist/
|
||||
/dist/
|
||||
/docs/_build/
|
||||
/htmlcov/
|
||||
/tmp/
|
||||
/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
|
||||
|
|
@ -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)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 82 KiB |
|
|
@ -0,0 +1,10 @@
|
|||
pre {
|
||||
padding: 8px 15px;
|
||||
}
|
||||
|
||||
div.contents {
|
||||
background-color: inherit;
|
||||
border: 0;
|
||||
margin-top: 0;
|
||||
padding-top: 0;
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
|
|
@ -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 %}
|
||||
|
|
@ -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",
|
||||
]
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
@ -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/>`_.
|
||||
|
|
@ -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
|
||||
|
|
@ -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)
|
||||
|
|
@ -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-cov
|
||||
pyxdg
|
||||
sphinx
|
||||
sphinx-autobuild
|
||||
stdeb
|
||||
twine
|
||||
wheel
|
||||
|
|
|
|||
Loading…
Reference in New Issue