diff --git a/docs/conf.py b/docs/conf.py index 1cf5f21..5c9ae17 100644 --- a/docs/conf.py +++ b/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), } diff --git a/docs/extension/_alpha.rst b/docs/extension/_alpha.rst new file mode 100644 index 0000000..3562eef --- /dev/null +++ b/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. diff --git a/docs/extension/_beta.rst b/docs/extension/_beta.rst new file mode 100644 index 0000000..6c2c65e --- /dev/null +++ b/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. diff --git a/docs/extension/django.rst b/docs/extension/django.rst new file mode 100644 index 0000000..104ad85 --- /dev/null +++ b/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: diff --git a/docs/extension/docker.rst b/docs/extension/docker.rst index f0fd17c..1d87d1e 100644 --- a/docs/extension/docker.rst +++ b/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 - brief overview but is neither complete nor definitive. +.. include:: _beta.rst Read the introduction: https://www.bonobo-project.org/with/docker +Source code +::::::::::: + +https://github.com/python-bonobo/bonobo-docker + + + diff --git a/docs/extension/index.rst b/docs/extension/index.rst index 53f10be..9edda12 100644 --- a/docs/extension/index.rst +++ b/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 diff --git a/docs/extension/jupyter.rst b/docs/extension/jupyter.rst index ed01d3b..75328a3 100644 --- a/docs/extension/jupyter.rst +++ b/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 diff --git a/docs/extension/selenium.rst b/docs/extension/selenium.rst index c262c13..9d8a8e0 100644 --- a/docs/extension/selenium.rst +++ b/docs/extension/selenium.rst @@ -1,9 +1,7 @@ -Selenium Extension -================== - -.. 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. +Working with Selenium +===================== +.. include:: _alpha.rst Writing web crawlers with Bonobo and Selenium is easy. diff --git a/docs/extension/sqlalchemy.rst b/docs/extension/sqlalchemy.rst index 734bbf6..bec1a49 100644 --- a/docs/extension/sqlalchemy.rst +++ b/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 - give a brief overview but is neither complete nor definitive. +.. include:: _beta.rst 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 + diff --git a/docs/tutorial/5-packaging.rst b/docs/tutorial/5-packaging.rst index fc53b91..d6556e1 100644 --- a/docs/tutorial/5-packaging.rst +++ b/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:`sqlalchemy` -* :doc:`django` -* :doc:`docker` +* :doc:`/extension/django` +* :doc:`/extension/docker` +* :doc:`/extension/jupyter` +* :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 `. diff --git a/docs/tutorial/django.rst b/docs/tutorial/django.rst deleted file mode 100644 index d5f7d32..0000000 --- a/docs/tutorial/django.rst +++ /dev/null @@ -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: - - diff --git a/docs/tutorial/docker.rst b/docs/tutorial/docker.rst deleted file mode 100644 index ea28c1a..0000000 --- a/docs/tutorial/docker.rst +++ /dev/null @@ -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 - - - diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index c4ae9e3..d179907 100644 --- a/docs/tutorial/index.rst +++ b/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 ` to have a deep dive in each concept. -* Explore the :doc:`Extensions ` to widen the possibilities. +* Explore the :doc:`Extensions ` to widen the possibilities: + + * :doc:`/extension/django` + * :doc:`/extension/docker` + * :doc:`/extension/jupyter` + * :doc:`/extension/sqlalchemy` + * Open the :doc:`References ` and start hacking like crazy. **You're not alone!** diff --git a/docs/tutorial/notebooks.rst b/docs/tutorial/notebooks.rst deleted file mode 100644 index ff141e1..0000000 --- a/docs/tutorial/notebooks.rst +++ /dev/null @@ -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 diff --git a/docs/tutorial/sqlalchemy.rst b/docs/tutorial/sqlalchemy.rst deleted file mode 100644 index 23f1078..0000000 --- a/docs/tutorial/sqlalchemy.rst +++ /dev/null @@ -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 - diff --git a/readthedocs-conda.yml b/readthedocs-conda.yml index 6552777..06541b1 100644 --- a/readthedocs-conda.yml +++ b/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 diff --git a/readthedocs.yml b/readthedocs.yml index c77e2a7..9937b05 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -3,3 +3,5 @@ conda: python: extra_requirements: - dev + - docker + - sqlalchemy