Merge pull request #21 from jedymatt/add-docs

Add docs

Author: jedymatt

.readthedocs.yaml

@@ -9,14 +9,15 @@ version: 2
 sphinx:
    configuration: docs/source/conf.py
    builder: html
-   fail_on_warning: true
+#    fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF
-formats:
-   - pdf
+formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
    version: "3.7"
    install:
+   - method: pip
+     path: .
    - requirements: docs/requirements.txt

docs/source/conf.py

@@ -51,4 +51,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']

docs/source/index.rst

@@ -6,11 +6,19 @@
 Welcome to sqlalchemyseed's documentation!
 ==========================================
 
+|pypi| |versions| |license| |build-status| |code-quality| |coverage|
+
+Project links: `Github`_ | `PyPI`_
+
+.. _Github: https://github.com/jedymatt/sqlalchemyseed
+.. _PyPI: https://pypi.org/project/sqlalchemyseed
+
 .. toctree::
     :maxdepth: 2
     :caption: Contents
 
     intro
+    relationships
     api
 
 Indices and tables
@@ -19,3 +27,28 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+
+.. |pypi| image:: https://img.shields.io/pypi/v/sqlalchemyseed
+    :alt: PyPI
+    :target: https://pypi.org/project/sqlalchemyseed/
+
+.. |versions| image:: https://img.shields.io/pypi/pyversions/sqlalchemyseed
+    :alt: PyPI - Python Version
+    :target: https://pypi.org/project/sqlalchemyseed/
+
+.. |license| image:: https://img.shields.io/pypi/l/sqlalchemyseed
+    :alt: PyPI - License
+    :target: https://github.com/jedymatt/sqlalchemyseed/blob/main/LICENSE
+
+.. |build-status| image:: https://app.travis-ci.com/jedymatt/sqlalchemyseed.svg?branch=main
+    :target: https://app.travis-ci.com/jedymatt/sqlalchemyseed
+
+.. |code-quality| image:: https://api.codeclimate.com/v1/badges/2ca97c98929b614658ea/maintainability
+   :target: https://codeclimate.com/github/jedymatt/sqlalchemyseed/maintainability
+   :alt: Maintainability
+
+
+.. |coverage| image:: https://codecov.io/gh/jedymatt/sqlalchemyseed/branch/main/graph/badge.svg?token=W03MFZ2FAG
+    :target: https://codecov.io/gh/jedymatt/sqlalchemyseed
+    

docs/source/intro.rst

@@ -1,7 +1,7 @@
 Introduction
 ============
 
-sqlalchemyseed is a SQLAlchemy seeder that supports nested relationships
+`sqlalchemyseed`_ is a SQLAlchemy seeder that supports nested relationships
 with an easy to read text files.
 
 Supported file types.
@@ -10,6 +10,8 @@ Supported file types.
 - yaml
 - csv
 
+.. _sqlalchemyseed: https://pypi.org/project/sqlalchemyseed/
+
 Installation
 ------------
 
@@ -36,12 +38,13 @@ Required dependencies
 Optional dependencies
 
 - yaml
+
   - PyYAML>=5.4.0
 
 Getting Started
 ---------------
 
-Here's a simple snippet to get started from :code:`main.py` file.
+Here's a simple snippet to get started from ``main.py`` file.
 
 .. code-block:: python
 
@@ -62,7 +65,7 @@ Here's a simple snippet to get started from :code:`main.py` file.
     session.commit()  # or seeder.session.commit()
 
 
-And the :code:`data.json` file.
+And the ``data.json`` file.
 
 .. code-block:: json
     

docs/source/relationships.rst

@@ -0,0 +1,39 @@
+Relationships
+=============
+
+To add reference attribute,
+add prefix to the attribute to differentiate reference attribute from normal ones.
+
+.. code-block:: json
+
+    {
+        "model": "models.Employee",
+        "data": {
+            "name": "John Smith",
+            "!company": {
+                "model": "models.Company",
+                "data": {
+                    "name": "MyCompany"
+                }
+            }
+        }
+    }
+
+Base on the example above, **name** is a normal attribute and **!company** is a reference attribute
+which translates to ``Employee.name`` and ``Employee.company``, respectively.
+
+.. note:: 
+    The default reference prefix is ``!`` and can be customized.
+    
+    Reference attribute can either be foreign key or relationship attribute.
+
+Customizing prefix
+------------------
+If you want '@' as prefix,
+you can just specify it to what seeder you use by
+adding ref_prefix='@' in the argument when initializing a seeder class.
+
+.. code-block:: python
+
+    seeder = Seeder(session, ref_prefix='@')
+