Skip to content
Permalink
Browse files

Clean up a lot of the existing documentation

  • Loading branch information...
lukasjuhrich committed Mar 3, 2019
1 parent 303073c commit 885828dfa1856bf3bd7b68acc98062893b71549b
Showing with 110 additions and 70 deletions.
  1. +34 −0 docs/source/backends.rst
  2. +1 −0 docs/source/conf.py
  3. +11 −7 docs/source/index.rst
  4. +37 −44 docs/source/model.rst
  5. +25 −17 docs/source/sipa.rst
  6. +1 −1 sipa/backends/extension.py
  7. +1 −1 sipa/initialization.py
@@ -0,0 +1,34 @@
.. py:module:: sipa.backends
==========================
Backends (Flask extension)
==========================

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

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

.. 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:
@@ -359,4 +359,5 @@
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'flask_flatpages': ('https://flask-login.readthedocs.io/en/latest/', None),
'flask': ('http://flask.pocoo.org/docs/1.0/', None),
}
@@ -6,13 +6,6 @@
Welcome to Sipa's documentation!
================================

Contents:

.. toctree::
:maxdepth: 2

model
sipa


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


Package reference
-----------------

.. toctree::
:maxdepth: 2

sipa
backends
model


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

@@ -1,70 +1,63 @@
=====
Model
=====
============
`sipa.model`
============

The `model` package contains
The `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

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

.. data:: backends
Sipa registers the following datasources:

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

Their implementations are in the corresponding modules

Datasource
----------
* :mod:`sipa.model.hss`
* :mod:`sipa.model.pycroft`
* :mod:`sipa.model.sample`

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.
`.user`
-------

.. automodule:: sipa.backends.datasource
:member-order: bysource
.. automodule:: sipa.model.user
:member-order: groupwise
:members:
:undoc-members:


User
----
`.fancy_property`
-----------------

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

Property
--------

.. automodule:: sipa.model.fancy_property
`.finance`
----------

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

.. automodule:: sipa.model.finance
:member-order: bysource
:members:
:private-members:
:undoc-members:
@@ -1,42 +1,50 @@
=====
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 `sipa.blueprints` package contains the actual endpoint definitions.
For an overview of flask blueprints, refer to the :ref:`flask documentation <flask:blueprints>`.

Mail
----
`.initialization`
-----------------

.. automodule:: sipa.initialization
:members:

`.mail`
-------

.. automodule:: sipa.mail
:members:

Units
-----
`.units`
--------

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


Base
----
`.base`
-------

.. automodule:: sipa.base
:members:


Babel
-----
`.babel`
--------

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


Flatpages
---------
`.flatpages`
------------

.. automodule:: sipa.flatpages
:members:
@@ -58,7 +58,7 @@ class Backends:
as its name, the email suffix, the user class, the initialization
method, and so on.
Originating from the needs of the [AG DSN](github.com/agdsn), the
Originating from the needs of the `AG DSN <https://github.com/agdsn>`_, the
user should not select the backend, but the location where he
lives. Thus, he selects a :py:class:`Dormitory`, which has not
only a name, but also a `display_name` and ip subnets. The latter
@@ -31,10 +31,10 @@
def init_app(app, **kwargs):
"""Initialize the Flask app located in the module sipa.
This initializes the Flask app by:
* calling the internal init_app() procedures of each module
* registering the Blueprints
* registering the Jinja global variables
:return: None
"""
load_config_file(app, config=kwargs.pop('config', None))
app.wsgi_app = ProxyFix(app.wsgi_app, app.config['NUM_PROXIES'])

0 comments on commit 885828d

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