Merge pull request #10 from saritasa-nest/update-docs

AUTHORS.rst

@@ -2,13 +2,14 @@
 Credits
 =======
 
-Development Lead
-----------------
+Author
+------
 
-* NikAzanov (Nikita Azanov)
+Saritasa, LLC
 
 Contributors
 ------------
 
 * yalef (Romaschenko Vladislav)
 * NikAzanov (Nikita Azanov)
+* ron8mcr (Roman Gorbil)

Makefile

@@ -56,11 +56,7 @@ coverage: ## check code coverage quickly with the default Python
 	$(BROWSER) htmlcov/index.html
 
 docs: ## generate Sphinx HTML documentation, including API docs
-	rm -f docs/import_export_extensions.rst
-	rm -f docs/modules.rst
-	sphinx-apidoc -o docs/ import_export_extensions
-	$(MAKE) -C docs clean
-	$(MAKE) -C docs html
+	DJANGO_SETTINGS_MODULE=tests.settings make html -C docs
 	$(BROWSER) docs/_build/html/index.html
 
 servedocs: docs ## compile the docs watching for changes

README.rst

@@ -34,19 +34,98 @@ adding the following features:
 * Support `drf-spectacular <https://github.com/tfranzel/drf-spectacular>`_ generated API schema
 * Additional fields and widgets (FileWidget, IntermediateM2MWidget, M2MField)
 
-Migration from django-import-export
------------------------------------
-Resources migration
-^^^^^^^^^^^^^^^^^^^
-Change ``Resource`` or ``ModelResource`` to
-``CeleryResource`` or ``CeleryModelResource`` respectively.
-
-Admin migration
-^^^^^^^^^^^^^^^
-Change ``ImportMixin``, ``ExportMixin``, ``ImportExportMixin``
-to ``CeleryImportMixin``, ``CeleryExportMixin`` or ``CeleryImportExportMixin`` respectively.
-
-License
--------
-* Free software: MIT license
+Installation
+-----
+
+To install `django-import-export-extensions`, run this command in your terminal:
+
+.. code-block:: console
+
+    $ pip install django-import-export-extensions
+
+Add `import_export_extensions` to INSTALLED_APPS
+
+.. code-block:: python
+
+    # settings.py
+    INSTALLED_APPS = (
+        ...
+        'import_export_extensions',
+    )
+
+Run `migrate` command to create ImportJob/ExportJob models and
+`collectstatic` to let Django collect package static files to use in the admin.
+
+.. code-block:: shell
+
+    $ python manage.py migrate
+    $ python manage.py collectstatic
+
+
+Usage
+-----
+
+Prepare resource for your model
+
+.. code-block:: python
+
+    # apps/books/resources.py
+    from import_export_extensions.resources import CeleryModelResource
+
+    from .. import models
+
+
+    class BookResource(CeleryModelResource):
+
+        class Meta:
+            model = models.Book
+
+Use `CeleryImportExportMixin` class and set `resource_class` in admin model
+to import/export via Django Admin
+
+.. code-block:: python
+
+    # apps/books/admin.py
+    from django.contrib import admin
+
+    from import_export_extensions.admin import CeleryImportExportMixin
+
+    from .. import resources
+
+
+    @admin.register(models.Book)
+    class BookAdmin(CeleryImportExportMixin, admin.ModelAdmin):
+        resource_class = resources.BookResource
+
+
+Prepare view sets to import/export via API
+
+.. code-block:: python
+
+    # apps/books/api/views.py
+    from .. import resources
+
+    from import_export_extensions.api import views
+
+
+    class BookExportViewSet(views.ExportJobViewSet):
+        resource_class = resources.BookResource
+
+
+    class BookImportViewSet(views.ImportJobViewSet):
+        resource_class = resources.BookResource
+
+
+Don't forget to `configure Celery <https://docs.celeryq.dev/en/stable/django/first-steps-with-django.html>`_
+if you want to run import/export in background
+
+
+Links:
+------
 * Documentation: https://django-import-export-extensions.readthedocs.io.
+* GitHub: https://github.com/saritasa-nest/django-import-export-extensions/
+* PyPI: https://pypi.org/project/django-import-export-extensions/
+
+License:
+________
+* Free software: MIT license

docs/Makefile

@@ -8,13 +8,15 @@ SPHINXPROJ    = import_export_extensions
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help html
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/api_admin.rst

@@ -0,0 +1,33 @@
+=====
+Admin
+=====
+
+.. automodule:: import_export_extensions.admin.model_admins.export_job_admin
+   :members:
+
+.. automodule:: import_export_extensions.admin.model_admins.import_job_admin
+   :members:
+
+.. automodule:: import_export_extensions.admin.model_admins.mixins
+   :members:
+
+.. automodule:: import_export_extensions.admin.forms.export_admin_form
+   :members:
+
+.. automodule:: import_export_extensions.admin.forms.import_admin_form
+   :members:
+
+.. automodule:: import_export_extensions.admin.mixins.base
+   :members:
+
+.. automodule:: import_export_extensions.admin.mixins.export_mixin
+   :members:
+
+.. automodule:: import_export_extensions.admin.mixins.import_export_mixin
+   :members:
+
+.. automodule:: import_export_extensions.admin.mixins.import_mixin
+   :members:
+
+.. automodule:: import_export_extensions.admin.widgets
+   :members:

docs/api_drf.rst

@@ -0,0 +1,39 @@
+====================
+API (Rest Framework)
+====================
+
+.. autoclass:: import_export_extensions.api.CreateExportJob
+   :members: create, validate
+
+.. autoclass:: import_export_extensions.api.CreateImportJob
+   :members: create, validate
+
+.. autoclass:: import_export_extensions.api.ExportJobSerializer
+   :members:
+
+.. autoclass:: import_export_extensions.api.ImportJobSerializer
+   :members:
+
+.. autoclass:: import_export_extensions.api.ProgressSerializer
+   :members:
+
+    .. attribute:: info
+       :type: ProgressInfoSerializer
+       :value: {"current": 0, "total": 0}
+
+        Shows current and total imported/exported values
+
+.. autoclass:: import_export_extensions.api.ProgressInfoSerializer
+   :members:
+
+    .. attribute:: current
+       :type: int
+       :value: 0
+
+       Shows number of imported/exported objects
+
+    .. attribute:: total
+       :type: int
+       :value: 0
+
+       Shows total objects to import/export

docs/api_models.rst

@@ -0,0 +1,9 @@
+======
+Models
+======
+
+.. autoclass:: import_export_extensions.models.ExportJob
+   :members:
+
+.. autoclass:: import_export_extensions.models.ImportJob
+   :members:

docs/conf.py

@@ -9,16 +9,17 @@
 sys.path.append(os.path.abspath("."))
 sys.path.append(os.path.abspath(".."))
 sys.path.append(os.path.abspath("../tests"))
-os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
+os.environ["DJANGO_SETTINGS_MODULE"] = "settings"
 
 django.setup()
+
 # -- General configuration ---------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.viewcode",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
 ]
 
@@ -144,4 +145,5 @@
 # intersphinx documentation
 intersphinx_mapping = {
     "tablib": ("https://tablib.readthedocs.io/en/stable/", None),
+    "django-import-export": ("https://django-import-export.readthedocs.io/en/latest/", None),
 }

docs/usage.rst → docs/getting_started.rst

@@ -1,6 +1,6 @@
-=====
-Usage
-=====
+===============
+Getting started
+===============
 
 Resources
 ---------

docs/index.rst

@@ -1,17 +1,43 @@
-Welcome to django-import-export-extensions documentation!
-=========================================================
+===============================
+Django import/export extensions
+===============================
+
+django-import-export-extensions is a Django application and library based on
+`django-import-export` library that provided extended features.
+
+**Features:**
+
+* Import/export resources in the background via Celery
+* Manage import/export jobs via Django Admin
+* DRF integration that allows to work with import/export jobs via API
+* Support `drf-spectacular <https://github.com/tfranzel/drf-spectacular>`_ generated API schema
+* Additional fields and widgets (FileWidget, IntermediateM2MWidget, M2MField)
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: User Guide
 
-   readme
    installation
-   usage
-   contributing
+   migrate_from_original_import_export
+   getting_started
    authors
    history
 
+.. toctree::
+   :maxdepth: 2
+   :caption: API Documentation
+
+   api_admin
+   api_models
+   api_drf
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Developers
+
+   contributing
+
+
 Indices and tables
 ==================
 * :ref:`genindex`