[docs] More documentation rewriting.

docs/conf.py

@@ -189,8 +189,9 @@ epub_exclude_files = ['search.html']
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
+    'django': ('https://docs.djangoproject.com/en/2.0/', 'https://docs.djangoproject.com/en/2.0/_objects/'),
     'fs': ('https://docs.pyfilesystem.org/en/latest/', None),
+    'python': ('https://docs.python.org/3', None),
     'requests': ('http://docs.python-requests.org/en/master/', None),
 }
 

docs/extension/_alpha.rst

@@ -0,0 +1,9 @@
+.. warning::
+
+    This extension is currently **ALPHA**.
+
+    Things will change, break, not work as expected, and the documentation is lacking some serious work.
+
+    This section is here to give a brief overview but is neither complete nor definitive.
+
+    You've been warned.

docs/extension/_beta.rst

@@ -0,0 +1,5 @@
+.. note::
+
+    This extension is currently **BETA**.
+
+    Things will change, and although we use it on some real-world software, it may, or may not, satisfy your needs.

docs/extension/django.rst

@@ -0,0 +1,53 @@
+Working with Django
+===================
+
+|bonobo| provides a lightweight integration with django, to allow to write management commands using |bonobo| graphs.
+
+Management Command
+::::::::::::::::::
+
+To write a management command with |bonobo|, just extend the :class:`bonobo.contrib.django.ETLCommand` class and
+override the `get_graph()` method.
+
+Example:
+
+.. code-block:: python
+
+    import bonobo
+    from bonobo.contrib.django import ETLCommand
+
+    class Command(ETLCommand):
+        def get_graph(self, **options):
+            graph = bonobo.Graph()
+            graph.add_chain(...)
+            return graph
+
+You can also override the `get_services()` method.
+
+One common recipe to do so is to import it from somewhere else and override it as a :obj:`staticmethod`:
+
+.. code-block:: python
+
+    import bonobo
+    from bonobo.contrib.django import ETLCommand
+
+    from myproject.services import get_services
+
+    class Command(ETLCommand):
+        get_services = staticmethod(get_services)
+
+        def get_graph(...):
+            ...
+
+Source code
+:::::::::::
+
+https://github.com/python-bonobo/bonobo/tree/master/bonobo/contrib/django
+
+Reference
+:::::::::
+
+.. automodule:: bonobo.contrib.django
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/extension/docker.rst

@@ -1,8 +1,14 @@
-Docker Extension
+Working with Docker
-================
+===================
 
-.. todo:: The `bonobo-docker` package is at a very alpha stage, and things will change. This section is here to give a
+.. include:: _beta.rst
-    brief overview but is neither complete nor definitive.
 
 Read the introduction: https://www.bonobo-project.org/with/docker
 
+Source code
+:::::::::::
+
+https://github.com/python-bonobo/bonobo-docker
+
+
+

docs/extension/index.rst

@@ -8,6 +8,7 @@ Most of them are available as optional extra dependencies, and the maturity stag
 .. toctree::
     :maxdepth: 2
 
+    django
     docker
     jupyter
     selenium

docs/extension/jupyter.rst

@@ -1,5 +1,7 @@
-Jupyter Extension
+Working with Jupyter
-=================
+====================
+
+.. include:: _beta.rst
 
 There is a builtin plugin that integrates (somewhat minimallistically, for now) bonobo within jupyter notebooks, so
 you can read the execution status of a graph within a nice (ok, not so nice) html/javascript widget.
@@ -37,3 +39,8 @@ webpack::
 
     ./node_modules/.bin/webpack
 
+
+Source code
+:::::::::::
+
+https://github.com/python-bonobo/bonobo/tree/master/bonobo/contrib/jupyter

docs/extension/selenium.rst

@@ -1,9 +1,7 @@
-Selenium Extension
+Working with Selenium
-==================
+=====================
-
-.. todo:: The `bonobo-selenium` package is at a very alpha stage, and things will change. This section is here to give a
-          brief overview but is neither complete nor definitive.
 
+.. include:: _alpha.rst
 
 Writing web crawlers with Bonobo and Selenium is easy.
 

docs/extension/sqlalchemy.rst

@@ -1,16 +1,37 @@
-SQLAlchemy Extension
+Working with SQL Databases
-====================
+==========================
 
-.. todo:: The `bonobo-sqlalchemy` package is at a very alpha stage, and things will change. This section is here to
+.. include:: _beta.rst
-          give a brief overview but is neither complete nor definitive.
 
 Read the introduction: https://www.bonobo-project.org/with/sqlalchemy
 
 Installation
 ::::::::::::
 
+To install the extension, use the `sqlalchemy` extra:
+
+.. code-block:: shell-session
+
+    $ pip install bonobo[sqlalchemy]
+
+.. note:: You can install more than one extra at a time separating the names with commas.
+
 Overview
 ::::::::
 
+There are two main tools provided by this extension. One reader, one writer.
+
+
 Details
 :::::::
+
+Reference
+:::::::::
+
+
+
+Source code
+:::::::::::
+
+https://github.com/python-bonobo/bonobo-sqlalchemy
+

docs/tutorial/5-packaging.rst

@@ -67,10 +67,10 @@ That's the end of the tutorial, you should now be familiar with all the basics.
 A few appendixes to the tutorial can explain how to integrate with other systems (we'll use the "fablabs" application
 created in this tutorial and extend it):
 
-* :doc:`notebooks`
+* :doc:`/extension/django`
-* :doc:`sqlalchemy`
+* :doc:`/extension/docker`
-* :doc:`django`
+* :doc:`/extension/jupyter`
-* :doc:`docker`
+* :doc:`/extension/sqlalchemy`
 
 Then, you can either to jump head-first into your code, or you can have a better grasp at all concepts by
 :doc:`reading the full bonobo guide </guide/index>`.

docs/tutorial/django.rst

@@ -1,24 +0,0 @@
-Working with Django
-===================
-
-.. warning::
-
-    This section does not exist yet, but it's in the plans to write it quite soon.
-
-    Meanwhile, you can check the source code and other links provided below.
-
-Source code
-:::::::::::
-
-https://github.com/python-bonobo/bonobo/tree/master/bonobo/contrib/django
-
-
-bonobo.contrib.django
-:::::::::::::::::::::
-
-.. automodule:: bonobo.contrib.django
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-

docs/tutorial/docker.rst

@@ -1,16 +0,0 @@
-Working with Docker
-===================
-
-.. warning::
-
-    This section does not exist yet, but it's in the plans to write it quite soon.
-
-    Meanwhile, you can check the source code and other links provided below.
-
-Source code
-:::::::::::
-
-https://github.com/python-bonobo/bonobo-docker
-
-
-

docs/tutorial/index.rst

@@ -22,22 +22,18 @@ Bonobo uses simple python and should be quick and easy to learn.
     4-services
     5-packaging
 
-
-**Integrations**
-
-.. toctree::
-    :maxdepth: 1
-
-    django
-    notebooks
-    sqlalchemy
-
 **What's next?**
 
 Once you're familiar with all the base concepts, you can...
 
 * Read the :doc:`Guides </guide/index>` to have a deep dive in each concept.
-* Explore the :doc:`Extensions </extension/index>` to widen the possibilities.
+* Explore the :doc:`Extensions </extension/index>` to widen the possibilities:
+
+  * :doc:`/extension/django`
+  * :doc:`/extension/docker`
+  * :doc:`/extension/jupyter`
+  * :doc:`/extension/sqlalchemy`
+
 * Open the :doc:`References </reference/index>` and start hacking like crazy.
 
 **You're not alone!**

docs/tutorial/notebooks.rst

@@ -1,13 +0,0 @@
-Working with Jupyter Notebooks
-==============================
-
-.. warning::
-
-    This section does not exist yet, but it's in the plans to write it quite soon.
-
-    Meanwhile, you can check the source code and other links provided below.
-
-Source code
-:::::::::::
-
-https://github.com/python-bonobo/bonobo/tree/master/bonobo/contrib/jupyter

docs/tutorial/sqlalchemy.rst

@@ -1,15 +0,0 @@
-Working with SQL Databases
-==========================
-
-.. warning::
-
-    This section does not exist yet, but it's in the plans to write it quite soon.
-
-    Meanwhile, you can check the source code and other links provided below.
-
-
-Source code
-:::::::::::
-
-https://github.com/python-bonobo/bonobo-sqlalchemy
-

readthedocs-conda.yml

@@ -27,6 +27,8 @@ dependencies:
   - unidecode==1.0.22
   - urllib3==1.22
   - whistle==1.0.0
+  # for contribs
+  - django>=2,<3
   # for docs
   - alabaster==0.7.10
   - sphinx-sitemap==0.2

readthedocs.yml

@@ -3,3 +3,5 @@ conda:
 python:
   extra_requirements:
     - dev
+    - docker
+    - sqlalchemy