Improve docs (#31)

* Improve docs

* Remove tests for deleted code

.pylintrc

@@ -1,20 +1,17 @@
 [MASTER]
 load-plugins=pylint_django, pylint_celery
 django-settings-module=config.settings.local
+ignore=migrations, tests
 
 [FORMAT]
 max-line-length=120
 
-[MESSAGES CONTROL]
-disable=missing-docstring,invalid-name
-
 [DESIGN]
 max-parents=13
 
 [TYPECHECK]
 generated-members=REQUEST,acl_users,aq_parent,"[a-zA-Z]+_set{1,2}",save,delete
 
 [SIMILARITIES]
-
 # Ignore imports when computing similarities.
 ignore-imports=yes

.readthedocs.yml

@@ -1,12 +1,20 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
 version: 2
 
+# Set the version of Python and other tools you might need
 build:
-  image: testing
+  os: ubuntu-22.04
+  tools:
+    python: '3.12'
 
+# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
+# Python requirements required to build your docs
 python:
-  version: 3.9
   install:
     - requirements: requirements/local.txt

CONTRIBUTING.rst

@@ -1,4 +1,175 @@
+.. _contributing:
+
+***************************
 Contributing to Democrasite
-===========================
+***************************
+
+.. index:: pip, virtualenv, PostgreSQL
+
+
+What to contribute
+==================
+
+Obviously this project doesn't work without people adding contributions,
+preferably many people adding lots of little contributions frequently. The
+project is oriented towards contributions which add new apps or features, with
+the constitution mechanic aimed at making it harder to significantly alter
+existing code than to add new things. The constitution is also aimed at
+protecting the core purpose and philosophy of the site, *not* its
+functionality. There are innumerable ways to just break the deployment or
+delivery of the website and I humbly ask that you refrain from intentionally
+doing so. If I see a pull request which breaks the site, I will close it. Use
+this website as a playground for whatever project you have that you want to
+see hosted as long as Django can serve it; I'd love for this to serve
+people's random creations. That being said, there are plenty of contributions
+and additions you could make to the site itself, such as to this document,
+which tells people nothing about how to contribute at the moment. Regardless of
+how you choose contribute, as long as it is in good faith, I appreciate it.
+
+
+.. Adapted from https://cookiecutter-django.readthedocs.io/en/latest/developing-locally.html
+
+Getting Up and Running
+======================
+
+Setting Up Development Environment
+----------------------------------
+
+Make sure to have the following on your host:
+
+* Python 3.12
+* PostgreSQL_
+* Redis_
+* Cookiecutter_
+
+First things first.
+
+#. Create a virtualenv::
+
+    $ python3.12 -m venv <virtual env path>
+
+#. Activate the virtualenv you have just created::
+
+    $ source <virtual env path>/bin/activate
+
+#. Install development requirements::
+
+    $ cd <what you have entered as the project_slug at setup stage>
+    $ pip install -r requirements/local.txt
+    $ git init # A git repo is required for pre-commit to install
+    $ pre-commit install
+
+   .. note::
+
+       the `pre-commit` hook exists in the generated project as default.
+       For the details of `pre-commit`, follow the `pre-commit`_ site.
+
+#. Create a new PostgreSQL database using createdb_::
+
+    $ createdb --username=postgres <project_slug>
+
+   ``project_slug`` is what you have entered as the project_slug at the setup stage.
+
+   .. note::
+
+       if this is the first time a database is created on your machine you might need an
+       `initial PostgreSQL set up`_ to allow local connections & set a password for
+       the ``postgres`` user. The `postgres documentation`_ explains the syntax of the config file
+       that you need to change.
+
+
+#. Set the environment variables for your database(s)::
+
+    $ export DATABASE_URL=postgres://postgres:<password>@127.0.0.1:5432/<DB name given to createdb>
+    # Optional: set broker URL if using Celery
+    $ export CELERY_BROKER_URL=redis://localhost:6379/0
+
+   .. seealso::
+
+       To help setting up your environment variables, you have a few options:
+
+       * create an ``.env`` file in the root of your project and define all the variables you need in it.
+         There's a .env.sample in the root of the repository which you can rename to serve as a basis.
+         Then you just need to have ``DJANGO_READ_DOT_ENV_FILE=True`` in your machine and all the variables
+         will be read.
+       * Use a local environment manager like `direnv`_
+
+#. Apply migrations::
+
+    $ python manage.py migrate
+
+#. See the application being served through Django development server::
+
+    $ python manage.py runserver 0.0.0.0:8000
+
+.. _PostgreSQL: https://www.postgresql.org/download/
+.. _Redis: https://redis.io/download
+.. _CookieCutter: https://github.com/cookiecutter/cookiecutter
+.. _createdb: https://www.postgresql.org/docs/current/static/app-createdb.html
+.. _initial PostgreSQL set up: https://web.archive.org/web/20190303010033/http://suite.opengeo.org/docs/latest/dataadmin/pgGettingStarted/firstconnect.html
+.. _postgres documentation: https://www.postgresql.org/docs/current/static/auth-pg-hba-conf.html
+.. _pre-commit: https://pre-commit.com/
+.. _direnv: https://direnv.net/
+
+
+Celery
+------
+
+If the project is configured to use Celery as a task scheduler then, by default, tasks are set to run on the main thread when developing locally instead of getting sent to a broker. However, if you have Redis setup on your local machine, you can set the following in ``config/settings/local.py``::
+
+    CELERY_TASK_ALWAYS_EAGER = False
+
+Next, make sure `redis-server` is installed (per the `Getting started with
+Redis guide`_) and run the server in one terminal::
+
+    $ redis-server
+
+Start the Celery worker by running the following command in another terminal::
+
+    $ celery -A config.celery_app worker --loglevel=info
+
+That Celery worker should be running whenever your app is running, typically as
+a background process, so that it can pick up any tasks that get queued. Learn
+more from the `Celery Workers Guide`_.
+
+You can also use Django admin to queue up tasks, thanks to the
+`django-celerybeat`_ package.
+
+.. _Getting started with Redis guide: https://redis.io/docs/getting-started/
+.. _Celery Workers Guide: https://docs.celeryq.dev/en/stable/userguide/workers.html
+.. _django-celerybeat: https://django-celery-beat.readthedocs.io/en/latest/
+
+
+Creating a webhook
+------------------
+
+:obj:`democrasite.webiscite` needs `webhooks`_ to find out about events on
+Github. `Create a webhook`_ in your fork of the repository, then generate a
+secret key for your hook and store it in your environment (either through your
+terminal or ``.env`` file) as ``GITHUB_SECRET_KEY``.
+
+To test your webhook, follow these `instructions`_. (If you have a preferred
+tool for exposing your local server, feel free to replace smee with it.) If you
+are using smee, be sure to run::
+
+   smee --url WEBHOOK_PROXY_URL --path /webhooks/github --port 8000
+
+to set the correct port and path.
+
+.. _webhooks: https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks
+.. _create a webhook: https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks
+.. _instructions: https://docs.github.com/en/webhooks/using-webhooks/handling-webhook-deliveries
+
+
+Automating the Repository
+-------------------------
+
+When a :class:`~democrasite.webiscite.models.Bill` passes, the corresponding
+pull request is automatically merged into the master branch, and if code blocks
+from the Constitution are moved, their locations are automatically updated in
+the remote constitution.json. In order to test this functionality in your fork
+of the repository, you will need to `create a Github personal access token`_
+and store it in your environment as ``GITHUB_TOKEN``. Make sure it at least has
+write access to your fork of the repository.
 
-Obviously this project doesn't work without people adding contributions, preferably many people adding lots of little contributions frequently. The project is oriented towards contributions which add new apps or features, with the constitution mechanic aimed at making it harder to significantly alter existing code than to add new things. The constitution is also aimed at protecting the core purpose and philosophy of the site, *not* its functionality. There are innumerable ways to just break the deployment or delivery of the website and I humbly ask that you refrain from intentionally doing so. If I see a pull request which breaks the site, I will close it. Use this website as a playground for whatever project you have that you want to see hosted as long as Django can serve it; I'd love for this to serve people's random creations. That being said, there are plenty of contributions and additions you could make to the site itself, such as to this document, which tells people nothing about how to contribute at the moment. Regardless of how you choose contribute, as long as it is in good faith, I appreciate it.
+.. _create a Github personal access token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

README.rst

@@ -19,14 +19,20 @@ Democrasite
 
 :License: MIT
 
-Democrasite is a website which automatically merges changes based on popular approval. For more information on the nature and purpose of the project, visit our `about page`_. This page is meant for people who want to clone the repository and contribute to the project. This project is approximately in beta development (hence the repository being named "cookiestocracy" – a reference to cookiecutter and `kakistocracy`_). The alpha version is `here`_ and the full version doesn't exist yet.
+Democrasite is a website which automatically merges changes based on popular
+approval. For more information on the nature and purpose of the project, visit
+our `about page`_. This page is meant for people who want to clone the
+repository and contribute to the project. This project is approximately in beta
+development (hence the repository being named "cookiestocracy" - a reference
+to cookiecutter and `kakistocracy`_). The alpha version is `here`_ and the
+full version doesn't exist yet.
 
 * Homepage:
   https://democrasite.herokuapp.com
 * Source code:
   https://github.com/mfosterw/cookiestocracy
 * Documentation:
-  https://democrasite.readthedocs.io
+  https://cookiestocracy.readthedocs.io/en/latest/
 
 .. _`about page`: https://democrasite.herokuapp.com/about/
 .. _`kakistocracy`: https://en.wikipedia.org/wiki/Kakistocracy
@@ -35,25 +41,23 @@ Democrasite is a website which automatically merges changes based on popular app
 Contributing
 ------------
 
-Please read the `contribution guide`_ and then see the basic commands below.
-It is also recommended that you rename ".env.sample" in the root of the
-repository to ".env" and set the environment variable
+Please read the :ref:`contribution guide <contributing>` and then see the basic
+commands below. It is also recommended that you rename ".env.sample" in the
+root of the repository to ".env" and set the environment variable
 ``DJANGO_READ_DOT_ENV_FILE=True`` so you can more easily keep track of your
 environment variables.
 
-.. _`contribution guide`: https://github.com/mfosterw/cookiestocracy/blob/master/CONTRIBUTING.rst
+.. _`contribution guide`: https://cookiestocracy.readthedocs.io/en/latest/CONTRIBUTING.html
 
 Basic Commands
 --------------
 
 Getting Started
 ^^^^^^^^^^^^^^^
 
-To start the server, run this command in the root of the repository:
+To start the server, run this command in the root of the repository::
 
-::
-
-  $ python manage.py runserver
+  $ python manage.py runserver_plus
 
 Setting Up Your Users
 ^^^^^^^^^^^^^^^^^^^^^
@@ -62,9 +66,19 @@ Setting Up Your Users
 
     $ python manage.py createsuperuser
 
-* To create a normal account, it's easiest to use the admin site. For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users.
+* To test logging in with a third party provider, you will need oauth keys from
+  the provider you're using. See the information on `django-allauth`_ for
+  `GitHub`_ and `Google`_ keys respectively, and once you have the keys create
+  environment variables named `<provider>-CLIENT-ID` and `<provider>-SECRET`.
+  Once you have these set up, log in normally with your provider. For
+  convenience, you can keep your normal user logged in on Chrome and your
+  superuser logged in on Firefox (or similar), so that you can see how the site
+  behaves for both kinds of users.
 
-* To test logging in with a third party provider, you will need oauth keys from the provider you're using. See the information on `django-allauth`_ for `GitHub`_ and `Google`_ keys respectively, and once you have the keys create environment variables named `<provider>-CLIENT-ID` and `<provider>-SECRET`. Once you have these set up, log in normally with your provider. A folder will be created in the repository root called "app-messages" which contains the confirmation email. Open the link in that file and your account will be activated.
+    .. note::
+        Accounts created through the admin page do not have a normal way to
+        sign in since there is no login page. To test working with
+        non-superuser accounts, please login through a social provider.
 
 .. _`django-allauth`: https://django-allauth.readthedocs.io/en/latest/overview.html
 .. _`GitHub`: https://django-allauth.readthedocs.io/en/latest/providers.html#github
@@ -73,11 +87,17 @@ Setting Up Your Users
 Type checks
 ^^^^^^^^^^^
 
-Running type checks with mypy:
+Running type checks with mypy::
+
+  $ mypy democrasite
+
+
+Running tests with py.test
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
-  $ mypy democrasite
+  $ pytest
 
 Test coverage
 ^^^^^^^^^^^^^
@@ -88,13 +108,6 @@ To run the tests, check your test coverage, and generate an HTML coverage report
     $ coverage html
     $ open htmlcov/index.html
 
-Running tests with py.test
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-::
-
-  $ pytest
-
 
 Celery
 ^^^^^^

config/settings/base.py

@@ -307,8 +307,7 @@
 ACCOUNT_USERNAME_REQUIRED = False
 ACCOUNT_ADAPTER = "democrasite.users.adapters.AccountAdapter"
 # https://docs.allauth.org/en/latest/socialaccount/configuration.html
-# TODO: determine if adapters should stay
-# SOCIALACCOUNT_ADAPTER = "democrasite.users.adapters.SocialAccountAdapter"
+SOCIALACCOUNT_ADAPTER = "democrasite.users.adapters.SocialAccountAdapter"
 SOCIALACCOUNT_EMAIL_AUTHENTICATION_AUTO_CONNECT = True
 # Enable social logins
 INSTALLED_APPS += [

democrasite/__init__.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-module-docstring
 __version__ = "0.1.0"
 __version_info__ = tuple(  # pylint: disable=consider-using-generator
     [

democrasite/conftest.py

@@ -1,3 +1,4 @@
+"""Global test fixtures for the project."""
 import pytest
 
 from democrasite.users.models import User
@@ -6,14 +7,16 @@
 
 @pytest.fixture(autouse=True)
 def media_storage(settings, tmpdir):
+    """Change the media root to a temporary directory."""
     settings.MEDIA_ROOT = tmpdir.strpath
 
 
 @pytest.fixture(autouse=True)
 def enable_db_access_for_all_tests(db):  # pylint: disable=unused-argument
-    pass
+    """Give all tests access to the database."""
 
 
 @pytest.fixture
 def user() -> User:
+    """Return a User instance."""
     return UserFactory()

democrasite/templates/pages/about.html

@@ -1,7 +1,7 @@
 {% extends "base.html" %}
 
 {% load i18n %}
-{% block title %}{% trans "About" %} - {{ block.super }}{% endblock %}
+{% block title %}{% trans "About" %} - {{ block.super }}{% endblock title %}
 
 {% block content %}
   <div class="row text-center justify-content-center">
@@ -54,7 +54,7 @@ <h5 class="card-title">{% blocktrans %}This is an example of a bill{% endblocktr
             <div class="progress-bar bg-danger" role="progressbar"></div>
           </div>
           <a href="javascript:;" class="float-left text-success mt-2 vote">
-            &check; {% trans "Yes" %}: <span class="num-yes-votes">0</span>
+            ✓ {% trans "Yes" %}: <span class="num-yes-votes">0</span>
           </a>
           <a href="javascript:;" class="float-right text-danger mt-2 vote">
             X {% trans "No" %}: <span class="num-no-votes">0</span>
@@ -67,4 +67,4 @@ <h5 class="card-title">{% blocktrans %}This is an example of a bill{% endblocktr
     <br>
     <p><a href="{% url 'privacy' %}">Privacy Policy</a></p>
   </div>
-{% endblock %}
+{% endblock content %}