From e18f2879fc4f427b1fde80e18fb65a90eeaef659 Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Wed, 23 Nov 2022 16:15:00 -0700 Subject: Add a lot more docs --- docs/contributing.rst | 99 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/features.rst | 51 +++++++++++++++++++++++++ docs/index.rst | 2 + requirements-dev.txt | 3 +- static/img/icon-32.png | Bin 0 -> 1633 bytes templates/base.html | 1 + 6 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 docs/contributing.rst create mode 100644 docs/features.rst create mode 100644 static/img/icon-32.png diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..164f5a5 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,99 @@ +Contributing +============ + +Takahē, as an open source project, could always do with more help, and if you +want to contribute we'd love help in the following areas: + +* Backend code development (Python) +* Frontend code development (HTML, CSS and very limited JavaScript) +* Visual design & UX (for our default UI, and the project site) +* Illustration (for the app, project site, and outreach materials) +* Writing (for our development and user documentation) + +If you're interested in helping out, join `our Discord server `_` +or email contact@jointakahe.org, and mention what you'd like to help with. + +All contributors are expected to abide by our `Code of Conduct `_. +We have zero tolerance for bigotry or discrimination. + +If you feel like someone is breaking the code of conduct, or is making you feel +unwelcome in a way not explicitly outlined in it, you can email us at +conduct@jointakahe.com. + + +Running Locally +--------------- + +If you wish to run Takahē locally, these instructions will help you do that. +It is worth noting, however, that this will only really let you test the UI +and local posting/follow functionality; to test ActivityPub itself and follow +other people, your installation **must be accessible from the internet**; +doing that securely is different enough per person that it is not covered here. + + +Direct installation +~~~~~~~~~~~~~~~~~~~ + +Takahē requires Python 3.10 or above, so you'll need that first. Clone the repo:: + + git clone git@github.com:jointakahe/takahe + +Then, ``cd`` into that directory and create and activate a virtual environment +(you can use other options, but this is the basic example):: + + python3 -m venv .venv + . .venv/bin/activate + +Then install the development requirements:: + + pip install -r requirements-dev.txt + +and enable the git commit hooks to do auto-formatting and linting +(if you don't do this, our CI system will reject your PRs until they match):: + + pre-commit install + +You will need to set your system to use development settings:: + + export DJANGO_SETTINGS_MODULE=takahe.settings.development + +You can run the web interface to see it at http://localhost:8000:: + + ./manage.py runserver + +You will need to run Stator in order to have background actions work:: + + ./manage.py runstator + +Make yourself a superuser account in order to log in: + + ./manage.py createsuperuser + +And you can run the tests with pytest:: + + pytest + + +Docker +~~~~~~ + +The docker build process will take care of much of the above, but you just have +to be sure that you're executing it from the project root. + +First, you need to build your image:: + + docker compose -f docker/docker-compose.yml build + +Then start the `compose` session:: + + docker compose -f docker/docker-compose.yml up + +At this point, you will be able to see the Web UI at http://localhost:8000 + +Once your session is up and running, you can make yourself a superuser account:: + + docker compose -f docker/docker-compose.yml exec web manage.py createsuperuser + +And you can run the tests inside your container:: + + docker compose -f docker/docker-compose.yml exec web pytest diff --git a/docs/features.rst b/docs/features.rst new file mode 100644 index 0000000..0d2e3ac --- /dev/null +++ b/docs/features.rst @@ -0,0 +1,51 @@ +Features +======== + +Takahē is currently in development, so it does not yet have all the features +of a full ActivityPub server. + +Currently, it supports: + +* Web UI only (but can be installed as a PWA) +* Creating posts, with CWs/summaries and visibility +* Receiving posts, with CWs/summaries, visibility, images +* Receiving post edits and deletions +* Creating and receiving boosts +* Creating and receiving likes +* Delivering mentions to those mentioned, and notifications for incoming mentions +* Following and unfollowing +* Reciving follows and unfollows +* A home timeline, a local timeline, and a federated timeline +* Profile pages with bios, icons, and header images +* Searching for users by exact handle +* Multiple domain support +* Multiple identity (per user account support) +* Signup flow +* Password reset flow + +Features planned for releases up to 1.0: + +* Handling replies and reply threading +* Adding images to posts, with descriptions +* Editing and deleting posts +* A mode where followers must be approved +* Emoji fetching and display +* Emoji creation at server level +* Searching for hashtags +* Server announcements system +* Moderation flagging system and queue +* Server defederation (blocking) +* IP and email domain banning +* Mastodon-compatible client API for use with apps + +Features that may make it into 1.0, or might be further out: + +* Creating polls on posts, and handling received polls +* Filter system for Home timeline +* Hashtag trending system with moderation +* Relay support + +Features on the long-term roadmap: + +* "Since you were gone" optional algorithmic timeline +* Seamless transfer from a Mastodon installation diff --git a/docs/index.rst b/docs/index.rst index 95c5a1e..340cc22 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,5 +15,7 @@ in alpha. For more information about Takahē, see :caption: Contents: installation + features domains stator + contributing diff --git a/requirements-dev.txt b/requirements-dev.txt index 6be4cd3..7f49057 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,9 +1,8 @@ -pre-commit~=2.20.0 -r requirements.txt +pre-commit~=2.20.0 black==22.10.0 flake8==5.0.4 isort==5.10.1 mock~=4.0.3 -pre-commit~=2.20.0 pytest-django~=4.5.2 pytest-httpx~=0.21 diff --git a/static/img/icon-32.png b/static/img/icon-32.png new file mode 100644 index 0000000..6f417b9 Binary files /dev/null and b/static/img/icon-32.png differ diff --git a/templates/base.html b/templates/base.html index 485e0d3..2fd92bf 100644 --- a/templates/base.html +++ b/templates/base.html @@ -9,6 +9,7 @@ +