Skip to content
Permalink
Browse files

Merge branch 'sphinx' into develop

  • Loading branch information...
lukasjuhrich committed Mar 3, 2019
2 parents 425199f + b86da5a commit 7b2c079bb3a3717fd6345985ee81b83072b13430
@@ -170,4 +170,5 @@ config.py
# documentation builds shall be checked into gh-pages or children of
# that
/docs/build
TAGS
TAGS
/docs/source/ref
@@ -33,12 +33,24 @@ script:
- "pycodestyle ."
- $DOCKER_COMPOSE build
- echo "Running complete test suite…" && $DOCKER_COMPOSE run --rm sipa_testing_no_volumes python manage.py test
- echo "Building documentation…" && make docs

after_success:
# we don't want to deploy from the testing compose file
# due to the additional testing requirements in this image
- docker-compose -f build/dev/docker-compose.yml build sipa
- sudo ./helpers/registry.sh all

deploy:
provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN # Set in the settings page of your repository, as a secure variable
keep-history: true
local_dir: build/html

before_cache:
- ./helpers/docker_cache.sh save_cache || echo "Cache saving failed"

stages:
- name: deploy
if: branch IN (master, develop)
@@ -17,7 +17,11 @@ translate:
poedit sipa/translations/en/LC_MESSAGES/messages.po
pybabel compile -d sipa/translations/

docs-clean:
$(MAKE) -C docs clean

docs:
sphinx-apidoc -o docs/source/ref sipa
$(MAKE) -C docs html

show_docs:
@@ -18,3 +18,4 @@ blinker~=1.4.0
factory-boy~=2.9.2
psycopg2~=2.7.3
Flask-QRcode~=2.0.2
typing-extensions~=3.7.2
@@ -6,3 +6,4 @@ profilehooks~=1.9.0
pycodestyle~=2.4.0
mypy~=0.620
typeshed~=0.0.1
sphinx~=1.8.4
@@ -0,0 +1,36 @@
.. py:module:: sipa.backends
==========================
Backends (Flask extension)
==========================

sipa.backends
-------------

.. autoclass:: Backends
:members:
:undoc-members:
:noindex:

.. data:: backends

A proxy pointing to the curent app's :py:data:`backends` object.


Datasource
----------

Sipa distinguishes between two concepts:

* A *Datasource* is the technical entity providing data, such as the
user class, the mail server, etc.
* A *Dormitory* is the entity that should be displayed as an option on
the login field. Therefore, its most important property is the
`display_name` and the datasource it belongs to. Also, it holds information about the IP
subnets, since these are bound to a location, and not the technical backend.

.. automodule:: sipa.backends.datasource
:member-order: bysource
:members:
:undoc-members:
:noindex:
@@ -37,6 +37,7 @@
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.intersphinx',
]

# Add any paths that contain templates here, relative to this directory.
@@ -127,7 +128,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'nature'
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -182,7 +183,15 @@

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'relations.html',
'searchbox.html',
'donate.html',
]
}

# Additional templates that should be rendered to pages, maps page names to
# template names.
@@ -344,3 +353,13 @@
# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False

### Intersphinx

intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'flask_login': ('https://flask-login.readthedocs.io/en/latest/', None),
'flask': ('http://flask.pocoo.org/docs/1.0/', None),
'ffp': ('https://flask-flatpages.readthedocs.io/en/latest/', None),
'sqla': ('https://docs.sqlalchemy.org/en/latest/', None),
}
@@ -6,13 +6,6 @@
Welcome to Sipa's documentation!
================================

Contents:

.. toctree::
:maxdepth: 2

model
sipa


Challenges
@@ -27,6 +20,18 @@ user's properties foran arbitrary backend.
This is


Package survey
-----------------

.. toctree::
:maxdepth: 2

sipa
backends
model
Complete Reference <ref/modules>


Indices and tables
==================

@@ -2,69 +2,63 @@
Model
=====

The `model` package contains
The :mod:`sipa.model` package mainly contains:

* The :py:class:`Backends` extension providing the infrastructure to
use multiple backends
* The implementations of such backends in the sub-packages.
#. :class:`~sipa.backends.datasource.Datasource` implementations for the
:py:mod:`sipa.backends` extension and everything that comes with it
(such as database setups)
#. An abstract :class:`BaseUser` class which defines all the properties a
backend's user should provide.
#. Related to the second, a smart property-like type which is able to express
whether a particular property is “supported” or not and whether it allows
for editing and / or deleting.

Backends
--------

This is automatically generated documentation from the `sipa.model` package.
Implemented backends
--------------------

.. automodule:: sipa.model
:members:
:exclude-members: Backends
Sipa registers the following datasources:

.. autoclass:: Backends
:members:
:undoc-members:
.. autodata:: sipa.model.AVAILABLE_DATASOURCES
:noindex:

.. data:: backends
Their implementations are in the corresponding modules

A proxy pointing to the curent app's :py:data:`backends` object.
* :mod:`sipa.model.hss`
* :mod:`sipa.model.pycroft`
* :mod:`sipa.model.sample`


Datasource
----------
User
----

Sipa distinguishes between two concepts:
.. class:: sipa.model.user.BaseUser
:noindex:

* A *Datasource* is the technical entity providing data, such as the
user class, the mail server, etc.
* A *Dormitory* is the entity that should be displayed as an option on
the login field. Therefore, its most important property is the
`display_name` and the datasource it belongs to. Also, it holds information about the IP
subnets, since these are bound to a location, and not the technical backend.

.. automodule:: sipa.model.datasource
:member-order: bysource
:members:
:undoc-members:
`.fancy_property`
-----------------

..
TODO use better documentation here!
User
----
.. automodule:: sipa.model.user
:member-order: groupwise
.. automodule:: sipa.model.fancy_property
:member-order: bysource
:members:
:undoc-members:
:noindex:

Finance
-------

.. automodule:: sipa.model.finance
:member-order: bysource
:members:
:private-members:
:undoc-members:
`.finance`
----------

Property
--------
Related to the information the user returns, we demand the following form
of the finance information:

.. automodule:: sipa.model.fancy_property
.. automodule:: sipa.model.finance
:member-order: bysource
:members:
:private-members:
:undoc-members:
:noindex:
@@ -1,46 +1,18 @@
=====
Sipa
=====
======
`sipa`
======

The `sipa` package contains everything necessary for the frontend.
The `sipa` package contains everything – things that are not grouped in
subpackages are mainly frontend-related.

`.blueprints`
-------------
The :mod:`sipa.blueprints` package contains the actual endpoint definitions.
For an overview of flask blueprints, refer to the :ref:`flask documentation <flask:blueprints>`.

Mail
----

.. automodule:: sipa.mail
:members:
`.flatpages`
------------

Units
-----

.. automodule:: sipa.units
:members:
:undoc-members:


Base
----

.. automodule:: sipa.base
:members:


Babel
-----

.. automodule:: sipa.babel
:members:
:undoc-members:
:exclude-members: request


Flatpages
---------

.. automodule:: sipa.flatpages
:members:
:undoc-members:
:private-members:
:special-members: __getattr__
:exclude-members: request
The :mod:`sipa.flatpages` module provides the :class:`~sipa.flatpages.CategorizedFlatPages`
flask extension, which is based on :mod:`Flask-FlatPages <ffp:flask_flatpages>`.
@@ -1,5 +1,6 @@
# -*- coding: utf-8 -*-
import logging
from typing import List, Optional

from babel import Locale, UnknownLocaleError, negotiate_locale
from flask import request, session
@@ -9,17 +10,12 @@
logger = logging.getLogger(__name__)


def possible_locales():
"""Return the locales usable for sipa.
:returns: Said Locales
:rtype: List of :py:obj:`Locale` s
"""
def possible_locales() -> List[Locale]:
"""Return the locales usable for sipa."""
return [Locale('de'), Locale('en')]


def get_user_locale_setting():
def get_user_locale_setting() -> Optional[Locale]:
"""Get a user's explicit locale setting, if available."""
locale_identifier = session.get('locale')
if locale_identifier is None:
@@ -60,7 +56,7 @@ def save_user_locale_setting():
session['locale'] = str(locale)


def select_locale():
def select_locale() -> str:
"""Select a suitable locale
Try to pick a locale from the following ordered sources:
@@ -70,8 +66,6 @@ def select_locale():
2. The best match according to the ``Accept-Language`` request header
:returns: The locale string
:rtype: str
"""
locale = get_user_locale_setting()
if locale is not None:
Oops, something went wrong.

0 comments on commit 7b2c079

Please sign in to comment.
You can’t perform that action at this time.