update docs and names

.pre-commit-config.yaml

@@ -26,5 +26,5 @@ repos:
       - id: flake8
         args:
           - --max-line-length=101
-          - --exclude=*/migrations/*,docs/*,*/snapshots/*
+          - --exclude=*/migrations/*,docs/*,*/snapshots/*,*/__init__.py
           - --ignore=E126,W503

codoc_views/codoc_base.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 
-from codoc.service import filters
-from codoc.service.export.codoc_view import view
+from codoc import filters, view
 
 import codoc
 

codoc_views/codoc_domain.py

@@ -2,9 +2,7 @@
 import codoc.domain.model
 import codoc.domain
 import codoc.domain.helpers
-from codoc.service import filters
-from codoc.service.export.codoc_view import view
-from codoc.service.parsing.node import get_identifier_of_object
+from codoc import filters, view
 
 
 @view(
@@ -19,9 +17,7 @@ def domain_model(graph):
 
     To actually utilize the classes, look at the service layer.
     """
-    graph = filters.get_children_of(
-        get_identifier_of_object(codoc.domain.model), keep_external_nodes=False
-    )(graph)
+    graph = filters.get_children_of(codoc.domain.model)(graph)
 
     return filters.include_only_classes(graph)
 
@@ -30,8 +26,6 @@ def domain_model(graph):
     label="Domain",
 )
 def domain(graph):
-    graph = filters.get_children_of(
-        get_identifier_of_object(codoc.domain), keep_external_nodes=False
-    )(graph)
+    graph = filters.get_children_of(codoc.domain)(graph)
 
     return graph

codoc_views/codoc_service_layer.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python3
 
-from codoc.service.parsing.node import get_description, get_identifier_of_object
-from codoc.service import filters
-from codoc.service.export.codoc_view import view
+from codoc.service.parsing.node import get_description
+from codoc import filters, view
 
 import codoc
 import codoc.service
@@ -55,9 +54,7 @@ def view_cli_dependencies(graph):
     """
     Here we show the dependencies of the CLI.
     """
-    return filters.get_children_of(
-        get_identifier_of_object(codoc.entrypoints), keep_external_nodes=True
-    )(graph)
+    return filters.get_children_of(codoc.entrypoints, keep_external_nodes=True)(graph)
 
 
 @view(

codoc_views/config.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-from codoc.service.graph import create_graph_of_module
+from codoc import new_graph
 
 from dotenv import load_dotenv
 
@@ -8,4 +8,4 @@
 
 def bootstrap(**kwargs):
     load_dotenv()
-    return create_graph_of_module(codoc, **kwargs)
+    return new_graph(codoc, **kwargs)

docs/conf.py

@@ -84,9 +84,13 @@
     "dark_logo": "img/logo-white.svg",
     "light_css_variables": {
         "color-brand-primary": "#f05623",
+        "admonition-title-font-size": "1.25rem",
+        "admonition-font-size": "1rem",
     },
     "dark_css_variables": {
         "color-brand-primary": "#f05623",
+        "admonition-title-font-size": "1.25rem",
+        "admonition-font-size": "1rem",
     },
 }
 html_static_path = ["_static"]

docs/examples.rst

@@ -0,0 +1,112 @@
+.. _`examples`:
+
+==========================
+Examples of view functions
+==========================
+
+This file contains examples of different views, explain what they do and why you
+might want them. They are merely examples and might need tweaking to work within
+your project
+
+Domain Model
+-------------
+Model diagram, class diagram or something else. People call it different
+things.
+
+To quote `Cosmic Python
+<https://www.cosmicpython.com/book/chapter_01_domain_model.html#_what_is_a_domain_model>`_,
+a highly recommended book:
+
+    The domain is a fancy way of saying the problem you’re trying to solve. Your
+    authors currently work for an online retailer of furniture. Depending on
+    which system you’re talking about, the domain might be purchasing and
+    procurement, or product design, or logistics and delivery. Most programmers
+    spend their days trying to improve or automate business processes; the
+    domain is the set of activities that those processes support.
+
+The following view function will show all the classes of your domain model,
+given that it's defined in ``myproject.domain``.
+
+.. code-block:: python
+
+    from codoc import filters, view
+
+    import myproject
+
+
+    @view(
+        label="Domain model (Classes)",
+    )
+    def domain_model(graph):
+        graph = filters.get_children_of(myproject.domain, keep_external_nodes=False)(graph)
+
+        return filters.include_only_classes(graph)
+
+Django models
+---------------------------
+In django you define your dataclasses by inheriting the *Model* class.
+Our filters currently do not support filtering based on inheritance, however by
+concatinating
+
+.. code-block:: python
+
+    from codoc import filters, view
+
+    import accounts.models
+    import billing.models
+
+    @view(
+        label="Domain Model (API)",
+    )
+    def all_models(graph):
+        graph = filters.include_only_classes(graph) | filters.include_only_modules(graph)
+
+        return (
+            filters.get_children_of(accounts.models)(graph)
+            | filters.get_children_of(billing.models)(graph)
+        )
+
+
+Clean Django module diagram
+---------------------------
+Django includes a few files that you might not be that interested in, like the
+``migrations`` file or ``tests`` of each app. We personally like to get a bit
+cleaner diagrams. We also don't always need external dependencies.
+The following custom made filter can help you here, and is
+utilized in the below example:
+
+.. code-block:: python
+
+    from codoc import view, filters
+
+    import accounts, billing
+
+    @view(
+        label="Internal modules",
+    )
+    def internal_modules(graph):
+        return remove_django_bloat(
+            remove_external_nodes(
+                filters.include_only_modules(graph)
+            )
+        )
+
+    def remove_external_nodes(graph):
+        return (
+            filters.get_children_of(accounts)(graph)
+            filters.get_children_of(accounts)(graph)
+            | filters.get_children_of(billing)(graph)
+        )
+
+    def remove_django_bloat(graph):
+        graph = filters.exclude_by_regex(r".migration")(graph)
+        graph = filters.exclude_by_regex(r".test")(graph)
+        graph = filters.exclude_by_regex(r".apps")(graph)
+        graph = filters.exclude_by_regex(r".snapshots")(graph)
+
+        return graph
+
+.. seealso::
+
+   - :ref:`filters`
+   - :ref:`how`

docs/faq.rst

@@ -84,6 +84,8 @@ Another possible problem is side-effects in your codebase. See :ref:`side_effect
 
 If you have circular dependencies, that will make codocpy crash some times, due to python crashing.
 
+If you are using Django, then it might be due to a `known bug <https://github.com/svadilfare/codoc-python/issues/4>`_ with ``admin.py``.
+
 We try our best at providing meaningful messages, where possible, however, it
 might be difficult at times. Codoc is a sensitive framework, but it will help
 you forever if you treat it right.
@@ -92,5 +94,7 @@ Is it secure?
 ----------------------
 You might fear losing your data. You shouldn't! Codoc doesn't access data and
 only reads your source code. It also only exports what you want, and you can
-always delete your data again. It's as safe as using Github, Sonarcloud, or other
-tools.
+always delete your data again. We, however, do not currently offer any
+self-hosted solutions, so if you want total control over your data, you are out
+of luck. Please contact us, if this is a big issue for you, and we might be able
+to help, and/or prioritize it higher.

docs/getting_started.rst

@@ -4,11 +4,11 @@
 Getting started
 ===============
 
+``codocpy`` requires: Python 3.6, 3.7, 3.8, 3.9.
+
 .. _`getstarted`:
 .. _`installation`:
 
-``codocpy`` requires: Python 3.6, 3.7, 3.8, 3.9.
-
 Install ``codoc-python``
 ----------------------------------------
 
@@ -25,63 +25,71 @@ Install ``codoc-python``
 
     $ codocpy
 
+Create a config
+-----------------------
+Everything Codoc related should be located inside a folder
+called ``codoc_views`` located at the root directory of your project.
+
+Start by creating a configuration file:
+
+You will also need a basic config file in the same folder, called ``config.py``.
+This file mainly needs a function called ``bootstrap`` to return a
+graph of the system in question. The example below returns a graph containing
+the ``myproject`` module, and it's direct dependencies:
+
+.. warning:: Using django? Please see :ref:`django` to bootstrap that correctly.
+             Please see :ref:`multi_mods` if your code exposes multiple packages.
+
+.. code-block:: python
+
+    # codoc_views/config.py
+    from codoc import new_graph
+
+    import myproject
+
+    def bootstrap(**kwargs):
+        return new_graph(myproject, **kwargs)
+
 .. _`simpleviews`:
 .. _`simpleview`:
 .. _`simple_view`:
 .. _`firstview`:
 
-Create your first View
------------------------
-
-We suggest grouping your views into a single folder called ``codoc_views``. This
-is the default folder that ``codocpy`` will look for.
+Your first *view function*
+--------------------------
 
-Inside this folder, create a new file called ``codoc_sample.py``:
+Inside the ``codoc_views`` folder, create a new python file, the name of which can be anything
+you choose. This file will include your first *view function*, which generates a view
+of the modules of your system.
 
 .. code-block:: python
 
-    from codoc.service import filters
-    from codoc.service.export import view
-
+    # codoc_views/module_views.py
+    from codoc import filters, view
     @view(
         label="Module View",
     )
     def modules(graph):
         """
-        This view contains all the modules that our project contains.
+        This view contains all the top level modules that our project contains.
         """
-        return filters.exclude_functions(filters.exclude_classes(graph))
-
-
-
-.. _`simple_config`:
-.. _`first_config`:
-
-Create a config
------------------------
-
-You will also need a basic config file in the same folder, called
-``conf.py`` in your views folder, so codocpy knows what project you want to analyze:
-
-.. code-block:: python
-
-    from codoc.service.graph import create_graph_of_module
-
-    import myproject
-
-    def bootstrap(**kwargs):
-        return create_graph_of_module(myproject, **kwargs)
-
-.. note:: Using django? Please see :ref:`django` to bootstrap that correctly.
+        module_graph = filters.include_only_modules(graph)
+        top_module_graph = filters.get_depth_based_filter(2)(module_graph)
+        return top_module_graph
 
 You can verify that codoc can find your views:
 
 .. code-block:: bash
 
     $ codocpy list_views
-    - view_modules
+    - module_views.modules
+
+.. warning:: Please make sure you are in the root directory of the project.
 
+This should be your filename appended with the name of each view function.
 
+.. _`simple_config`:
+.. _`first_config`:
 
 
 Publishing your view
@@ -104,7 +112,6 @@ and scroll to the bottom and fetch your API key of choice.
 This has to be set as an environmental variable called ``CODOC_API_KEY``. One
 way of doing is simply by writing:
 
-
 .. code-block:: bash
 
     $ export CODOC_API_KEY="f5f9c07f4ce96aeee3aeb32faf35c0e821b8c831"
@@ -117,15 +124,16 @@ You can now publish your views:
     Publishing Module View...
     published at https://codoc.org/app/view/181
 
-
 .. note:: Did it failed? Codoc is a bit sensitive, sadly. Read :ref:`it_crashed`
           for what to do.
 
-Your view is now published, and you can view at the returned domain (in our
-example https://codoc.org/app/graph/181) which shows a public example from our
-`sample project <https://github.com/svadilfare/codoc-python-example>`_
+Your view is now published, and you can view it at the URL shown in your console
+(in our example https://codoc.org/app/graph/181) which offers a public example
+from our `sample project <https://github.com/svadilfare/codoc-python-example>`_
 
 .. seealso::
+
+   - :ref:`examples`
    - :ref:`how`
    - :ref:`filters`
    - :ref:`views`

docs/index.rst

@@ -42,16 +42,18 @@ Features
 - Historical information about prior views
 - **COMING SOON** See graphical representation of test coverage, contributors etc.
 - **COMING SOON** Get live monitoring data on your views
+- **COMING SOON** Comments and dialogue about views.
 - **COMING SOON** A git bot that provide context for pull requests
 - **COMING SOON** A variety of export possibilities
-- **COMING SOON** Sphinx (and other) integrations
+- **COMING SOON** Sphinx, Confluence, GitBook (and other) integrations
 
 Content
 ---------------
 .. toctree::
    :maxdepth: 3
 
    getting_started
+   examples
    reference/index
    faq