++docs

uralbash · Jul 7, 2016 · 503c573 · 503c573
1 parent fa0095b
commit 503c573
Show file tree

Hide file tree

Showing 5 changed files with 131 additions and 128 deletions.
diff --git a/README.rst b/README.rst
@@ -1,14 +1,14 @@
-|Build Status| |Coverage Status| |PyPI|
+|Build Status| |Coverage Status|
 
 Library for implementing Modified Preorder Tree Traversal with your
 SQLAlchemy Models and working with trees of Model instances, like
-django-mptt. Docs http://sqlalchemy-mptt.readthedocs.org/
+django-mptt. Docs http://sqlalchemy-mptt.readthedocs.io/
 
 .. image:: https://cdn.rawgit.com/uralbash/sqlalchemy_mptt/master/docs/img/2_sqlalchemy_mptt_traversal.svg
    :alt: Nested sets traversal
    :width: 800px
 
-The nested set model is a particular technique for representing nested
+The nested set model is a particular technique for representing nested 
 sets (also known as trees or hierarchies) in relational databases.
 
 Installing
@@ -30,7 +30,7 @@ Source:
 
 .. code-block:: bash
 
-    python setup.py install
+    pip install -e .
 
 Usage
 -----
@@ -56,9 +56,7 @@ Add mixin to model
         def __repr__(self):
             return "<Node (%s)>" % self.id
 
-    Tree.register_tree()
-
-Now you can add, move and delete obj
+Now you can add, move and delete obj!
 
 Insert node
 -----------
@@ -256,15 +254,17 @@ Move to top level
                                |          |
             4               8(20)9    12(22)13
 
-
 Support and Development
 =======================
 
-To report bugs, use the `issue tracker <https://github.com/uralbash/sqlalchemy_mptt/issues>`_.
+To report bugs, use the `issue tracker
+<https://github.com/uralbash/sqlalchemy_mptt/issues>`_.
 
-We welcome any contribution: suggestions, ideas, commits with new futures, bug fixes, refactoring, docs, tests, translations etc
+We welcome any contribution: suggestions, ideas, commits with new
+futures, bug fixes, refactoring, docs, tests, translations, etc...
 
-If you have question, contact me sacrud@uralbash.ru or IRC channel #sacrud
+If you have question, contact me sacrud@uralbash.ru or #sacrud IRC
+channel |IRC Freenode|
 
 License
 =======
@@ -275,5 +275,5 @@ The project is licensed under the MIT license.
    :target: https://travis-ci.org/uralbash/sqlalchemy_mptt
 .. |Coverage Status| image:: https://coveralls.io/repos/uralbash/sqlalchemy_mptt/badge.png
    :target: https://coveralls.io/r/uralbash/sqlalchemy_mptt
-.. |PyPI| image:: http://img.shields.io/pypi/dm/sqlalchemy_mptt.svg
-   :target: https://pypi.python.org/pypi/sqlalchemy_mptt
+.. |IRC Freenode| image:: https://img.shields.io/badge/irc-freenode-blue.svg
+   :target: https://webchat.freenode.net/?channels=sacrud
diff --git a/docs/contribute.rst b/docs/contribute.rst
diff --git a/docs/example.rst → docs/crud.rst b/docs/example.rst → docs/crud.rst
@@ -1,85 +1,8 @@
-Example
--------
-
-Initalize
-~~~~~~~~~
-
-Create model with MPTT mixin and register events.
-
-.. code-block:: python
-    :linenos:
-
-    from sqlalchemy import Column, Integer, Boolean
-    from sqlalchemy.ext.declarative import declarative_base
-
-    from sqlalchemy_mptt.mixins import BaseNestedSets
-
-    Base = declarative_base()
-
-
-    class Tree(Base, BaseNestedSets):
-        __tablename__ = "tree"
-
-        id = Column(Integer, primary_key=True)
-        visible = Column(Boolean)  # you custom field
-
-        def __repr__(self):
-            return "<Node (%s)>" % self.id
-
-Events
-~~~~~~
-
-Events registered automatically, but you can do it manually:
-
-.. code-block:: python
-
-   from sqlalchemy_mptt import tree_manager
-
-   tree_manager.register_events()  # register events before_insert,
-                                   # before_update and before_delete
-
-Or remove events if it required:
-
-.. code-block:: python
-
-   from sqlalchemy_mptt import tree_manager
-
-   tree_manager.register_events(remove=True)  # remove events before_insert,
-                                              # before_update and before_delete
-
-Data structure
-~~~~~~~~~~~~~~
-
-Fill table with records, for example, as shown in the picture
-
-.. image:: img/2_sqlalchemy_mptt_traversal.svg
-    :width: 500px
-    :alt: SQLAlchemy MPTT (nested sets)
-    :align: left
-
-Represented data of tree like dict
-
-.. code-block:: python
-
-    tree = (
-        {'id':  '1',                  'parent_id': None},
-
-        {'id':  '2', 'visible': True, 'parent_id':  '1'},
-        {'id':  '3', 'visible': True, 'parent_id':  '2'},
-
-        {'id':  '4', 'visible': True, 'parent_id':  '1'},
-        {'id':  '5', 'visible': True, 'parent_id':  '4'},
-        {'id':  '6', 'visible': True, 'parent_id':  '4'},
-
-        {'id':  '7', 'visible': True, 'parent_id':  '1'},
-        {'id':  '8', 'visible': True, 'parent_id':  '7'},
-        {'id':  '9',                  'parent_id':  '8'},
-        {'id': '10',                  'parent_id':  '7'},
-        {'id': '11',                  'parent_id': '10'},
-    )
+CRUD
+====
 
 INSERT
-~~~~~~
+------
 
 Insert node with parent_id==6
 
@@ -118,7 +41,7 @@ After insert
     4                      10(23)11  16(9)17   20(11)21
 
 UPDATE
-~~~~~~
+------
 
 Set parent_id=5 for node with id==8
 
@@ -158,9 +81,8 @@ After update
                            |
         5                9(9)10
 
-
 DELETE
-~~~~~~
+------
 
 Delete node with id==4
 
@@ -198,19 +120,3 @@ After delete
     4                     8(9)9    12(11)13
 
 For more example see :mod:`sqlalchemy_mptt.tests.TestTree`
-
-
-SESSION
-~~~~~~~
-
-To work correctly after flush you should use :mod:`sqlalchemy_mptt.mptt_sessionmaker`
-
-.. code-block:: python
-    :linenos:
-
-    from sqlalchemy import create_engine
-    from sqlalchemy.orm import sessionmaker
-    from sqlalchemy_mptt import mptt_sessionmaker
-
-    engine = create_engine('...')
-    Session = mptt_sessionmaker(sessionmaker(bind=engine))
diff --git a/docs/index.rst b/docs/index.rst
@@ -25,22 +25,35 @@ API:
 
    sqlalchemy_mptt
 
-Project uses sqlalchemy_mptt
-----------------------------
+Where used
+----------
 
 * ps_tree_
 * pyramid_pages_
 * your project ...
 
-.. raw:: html
+Manual
+------
 
-    <br clear="all" />
+.. toctree::
+
+    initialize.rst
+    crud.rst
+
+A lot of examples and logic in
+:py:mod:`sqlalchemy_mptt.tests.tree_testing_base`
+
+Support and Development
+=======================
 
-.. include:: example.rst
+To report bugs, use the `issue tracker
+<https://github.com/uralbash/sqlalchemy_mptt/issues>`_.
 
-A lot of examples and logic in :py:mod:`sqlalchemy_mptt.tests.tree_testing_base`
+We welcome any contribution: suggestions, ideas, commits with new
+futures, bug fixes, refactoring, docs, tests, translations, etc...
 
-.. include:: contribute.rst
+If you have question, contact me sacrud@uralbash.ru or #sacrud IRC
+channel |IRC Freenode|
 
 Indices and tables
 ==================
@@ -51,3 +64,5 @@ Indices and tables
 
 .. _ps_tree: https://github.com/sacrud/ps_tree
 .. _pyramid_pages: https://github.com/uralbash/pyramid_pages
+.. |IRC Freenode| image:: https://img.shields.io/badge/irc-freenode-blue.svg
+   :target: https://webchat.freenode.net/?channels=sacrud
diff --git a/docs/initialize.rst b/docs/initialize.rst
@@ -0,0 +1,91 @@
+Initalize
+=========
+
+Create model with MPTT mixin and register events.
+
+.. code-block:: python
+    :linenos:
+
+    from sqlalchemy import Column, Integer, Boolean
+    from sqlalchemy.ext.declarative import declarative_base
+
+    from sqlalchemy_mptt.mixins import BaseNestedSets
+
+    Base = declarative_base()
+
+
+    class Tree(Base, BaseNestedSets):
+        __tablename__ = "tree"
+
+        id = Column(Integer, primary_key=True)
+        visible = Column(Boolean)  # you custom field
+
+        def __repr__(self):
+            return "<Node (%s)>" % self.id
+
+Events
+------
+
+Events registered automatically, but you can do it manually:
+
+.. code-block:: python
+
+   from sqlalchemy_mptt import tree_manager
+
+   tree_manager.register_events()  # register events before_insert,
+                                   # before_update and before_delete
+
+Or remove events if it required:
+
+.. code-block:: python
+
+   from sqlalchemy_mptt import tree_manager
+
+   tree_manager.register_events(remove=True)  # remove events before_insert,
+                                              # before_update and before_delete
+
+Data structure
+--------------
+
+Fill table with records, for example, as shown in the picture
+
+.. image:: img/2_sqlalchemy_mptt_traversal.svg
+    :width: 500px
+    :alt: SQLAlchemy MPTT (nested sets)
+    :align: left
+
+Represented data of tree like dict
+
+.. code-block:: python
+
+    tree = (
+        {'id':  '1',                  'parent_id': None},
+
+        {'id':  '2', 'visible': True, 'parent_id':  '1'},
+        {'id':  '3', 'visible': True, 'parent_id':  '2'},
+
+        {'id':  '4', 'visible': True, 'parent_id':  '1'},
+        {'id':  '5', 'visible': True, 'parent_id':  '4'},
+        {'id':  '6', 'visible': True, 'parent_id':  '4'},
+
+        {'id':  '7', 'visible': True, 'parent_id':  '1'},
+        {'id':  '8', 'visible': True, 'parent_id':  '7'},
+        {'id':  '9',                  'parent_id':  '8'},
+        {'id': '10',                  'parent_id':  '7'},
+        {'id': '11',                  'parent_id': '10'},
+    )
+
+Session
+-------
+
+To work correctly after flush you should use :mod:`sqlalchemy_mptt.mptt_sessionmaker`
+
+.. code-block:: python
+    :linenos:
+
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import sessionmaker
+    from sqlalchemy_mptt import mptt_sessionmaker
+
+    engine = create_engine('...')
+    Session = mptt_sessionmaker(sessionmaker(bind=engine))