Update docs (#21)

* Show bottom relbar

* Add usage

* Fix lxml

* Run allauth tests

Author: aclark4life

docs/source/conf.py

@@ -25,3 +25,7 @@
 
 html_theme = "alabaster"
 html_static_path = ["_static"]
+html_theme_options = {
+    "show_relbar_top": False,
+    "show_relbar_bottom": True,
+}

docs/source/index.rst

@@ -25,7 +25,8 @@ Table of Contents
 .. toctree::
    :maxdepth: 3
 
-   installation/index
+   installation
+   usage
    third-party-library-support/index
    supported-libraries/index
 

docs/source/installation.rst

@@ -0,0 +1,38 @@
+Installation
+============
+
+Clone the repository
+--------------------
+
+::
+
+    git clone https://github.com/mongodb-labs/django-mongodb-cli
+    cd django-mongodb-cli
+
+
+Create a virtual environment
+----------------------------
+
+::
+
+    python -m venv .venv
+    source .venv/bin/activate
+
+
+Install ``dm`` command
+----------------------
+
+::
+
+    python -m pip install -e .
+
+.. _additional-installation-steps:
+
+Additional installation steps
+-----------------------------
+
+Clone third-party library repositories and install dependencies with ``just``.
+
+::
+
+    just install

docs/source/installation/index.rst

@@ -0,0 +1,19 @@
+Usage
+=====
+
+Run third-party library tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+django-allauth
+++++++++++++++
+
+.. warning::
+
+   If you install ``lxml`` and ``xmlsec`` via ``pip`` instead of
+   ``just install`` :ref:`as described here <additional-installation-steps>`
+   you may encounter test failures due to `issues like this one
+   <https://github.com/xmlsec/python-xmlsec/issues/320>`_.
+
+::
+
+    dm repo test django-allauth

docs/source/usage.rst

@@ -5,9 +5,11 @@ install: pip-install git-clone dev-install
 alias i := install
 
 dev-install:
+    dm repo install django
     dm repo install django-mongodb-backend
     dm repo install django-mongodb-extensions
     dm repo install mongo-python-driver
+    dm repo install python-xmlsec
 
 
 demo:
@@ -21,12 +23,15 @@ alias d := demo
 
 [group('git')]
 git-clone:
+    dm repo clone django
+    dm repo clone django-allauth
     dm repo clone django-mongodb-app
     dm repo clone django-mongodb-backend
     dm repo clone django-mongodb-extensions
     dm repo clone django-mongodb-project
     dm repo clone django-mongodb-templates
     dm repo clone mongo-python-driver
+    dm repo clone python-xmlsec
 
 # ---------------------------------------- django ----------------------------------------
 
@@ -63,6 +68,7 @@ db-init:
 [group('python')]
 pip-install: check-venv
     brew install libxml2 libxmlsec1 pkg-config
+    pip install lxml==5.3.2 --no-binary :all:
     pip install -U pip
     pip install -e .
     pre-commit install

justfile

@@ -12,7 +12,6 @@ dependencies = [
     "dj-database-url",  # For startproject and testing with postgres
     "fido2",  # For django-allauth
     "html5lib",  # Required by django-debug-toolbar
-    "lxml==5.2.1",  # For django-allauth
     "psycopg2",  # For django-allauth
     "python3-openid",  # For django-allauth
     "python3-saml",  # For django-allauth