Merge pull request #10 from maykinmedia/feature/5-port-api-styles-and-templates

Port API project styles and templates

Author: sergei-maertens

.editorconfig

@@ -7,7 +7,7 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.{scss,sass}]
+[*.css]
 indent_size = 2
 
 [*.{yml,yaml}]

.github/workflows/ci.yml

@@ -43,10 +43,30 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  e2e_tests:
+    runs-on: ubuntu-latest
+    name: Run the end-to-end tests
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          pip install tox tox-gh-actions pytest-playwright
+          playwright install --with-deps chromium
+
+      - name: Run tests
+        run: tox -e e2e
+
   publish:
     name: Publish package to PyPI
     runs-on: ubuntu-latest
-    needs: tests
+    needs:
+      - tests
+      - e2e_tests
     environment: release
     permissions:
       id-token: write

.gitignore

@@ -55,7 +55,7 @@ reports
 # Django stuff:
 *.log
 local_settings.py
-db.sqlite3
+testapp/*.db
 
 # Flask stuff:
 instance/

README.rst

@@ -64,9 +64,6 @@ Run the tests with:
 
     tox
 
-Note that if you run ``pytest`` directly, some tests are expected to fail when you have
-all optional dependency groups installed.
-
 .. |build-status| image:: https://github.com/maykinmedia/django-common/workflows/Run%20CI/badge.svg
     :alt: Build status
     :target: https://github.com/maykinmedia/django-common/actions?query=workflow%3A%22Run+CI%22

docs/apis.rst

@@ -0,0 +1,127 @@
+.. _apis:
+
+============
+API projects
+============
+
+Many of the Maykin projects are API-first projects with only a minimum of "public
+frontend" requirements. maykin-common facilitates these by providing some base
+templates, CSS and JS for the landing page.
+
+Templates
+=========
+
+Two templates are provided from the library that you should extend:
+
+* ``maykin_common/api/index_base.html``, use it in ``index.html`` for your landing page
+* ``maykin_common/api/includes/footer.html``, use it to extend your
+  ``includes/footer.html`` from
+
+You'll need to make some modifications to the root ``urls.py`` and ``master.html`` to
+wire up everything automatically.
+
+.. tip:: With the default project setup, the necessary CSS and Javascript are
+   automatically loaded. If you use another master template, make sure to define the
+   ``view_class``, ``extra_css`` and ``content`` blocks to override.
+
+``maykin_common/api/index_base.html``
+-------------------------------------
+
+Provides the general scaffolding of the language page with the tabbed layout for
+Dutch and English content and the general branding.
+
+In your child template, make sure to override the blocks that are specific to your
+project:
+
+* ``page_title``
+* ``page_subtitle``
+* ``content_nl``
+* ``content_en``
+* ``license_link``
+
+``maykin_common/api/includes/footer.html``
+------------------------------------------
+
+Provides the standard footer layout with sensible defaults. You can override (default)
+values by clever usage of the ``with`` tag:
+
+.. code-block:: django
+
+    {% block footer %}
+        {% capture as issues_link silent %}<a class="link link--muted" href="https://github.com/maykinmedia/awesome-project/issues">issues</a>{% endcapture %}
+
+        {% with issues_link=issues_link %}
+            {{ block.super }}
+        {% endwith %}
+
+    {% endblock %}
+
+.. tip:: Consider installing django-capture-tag for cleaner templates, like the example
+   above.
+
+Blocks you'll typically want to override are:
+
+* ``footer``
+* ``links`` - the middle column with project-specific links
+
+Other blocks you can override are:
+
+* ``other_links`` - the links in the rightmost column
+
+Stylesheets
+===========
+
+The base template automatically loads the ``maykin_common/css/api.css`` stylesheets
+which contains the majority of the styles for the landing page components.
+
+.. note:: While the default template uses font-awesome class names, the font-awesome
+   stylesheet is **not** included as we want to avoid any frontend toolchains as long
+   as possible. You have to make sure your project includes the styles and font assets
+   yourself.
+
+.. tip:: No default values are provided, however the default-project template does
+   provide a starter setup in the ``_os_api`` directory.
+
+The CSS is written with theming in mind. At the time of writing, the following CSS
+variables are supported, grouped by component:
+
+**Page title**
+
+* ``--page-title-color``
+* ``--page-title-font-family``
+
+**Footer**
+
+* ``--footer-border-color``
+
+**Tabs**
+
+* ``--tabs-border-color``
+* ``--tabs-item-color``
+* ``--tabs-item-hover-color``
+* ``--tabs-item-hover-border-color``
+
+**Button**
+
+* ``--button-color``
+* ``--button-background-color``
+* ``--button-hover-background-color``
+* ``--button-alert-background-color``
+* ``--button-alert-hover-background-color``
+
+**Link**
+
+* ``--link-color``
+* ``--link-color-hover``
+* ``--link-color-muted``
+
+Javascript
+==========
+
+We ship a minimal amount of Javascript and it's automatically loaded from the base
+template.
+
+``maykin_common/js/nav-tabs.js``
+--------------------------------
+
+Controls the (active) tab state for the ``.tabs`` component.

docs/index.rst

@@ -45,6 +45,7 @@ Features
    :caption: Contents:
 
    quickstart
+   apis
    maykin_common/settings
    maykin_common/checks
    maykin_common/context_processors

maykin_common/context_processors.py

@@ -6,6 +6,8 @@ def settings(request):
     public_settings = (
         "GOOGLE_ANALYTICS_ID",
         "PROJECT_NAME",
+        "RELEASE",
+        "GIT_SHA",
     )
 
     context = {