🚧 Created main directives skeletons

autoflex/__init__.py

@@ -10,7 +10,7 @@
 
 from typing import Any, Dict
 from .install import install_verification
-from .directives import AutoFlexDirective
+from autoflex.directives import AutoFlex, FlexTree
 
 __version__ = "0.0.1"
 __author__ = "Dario Quintero Dominguez"
@@ -20,7 +20,8 @@
 def setup(app) -> Dict[str, Any]:
     """Add icon node to the sphinx builder."""
     print("Started loading `autoflex` extension.")
-    app.add_directive("autoflex", AutoFlexDirective)
+    app.add_directive("autoflex", AutoFlex)
+    app.add_directive("flextree", FlexTree)
     # load the icon node/role
     # app.add_node(icon_node, **_NODE_VISITORS)  # type: ignore
     # app.add_role("icon", Icon())

autoflex/directives/__init__.py

@@ -0,0 +1,2 @@
+from .autoflex import AutoFlex
+from .flextree import FlexTree

autoflex/directives/autoflex.py

@@ -0,0 +1,49 @@
+import pydantic
+from docutils.parsers import rst
+from typing import Any
+
+
+class AutoFlex(rst.Directive):
+    """
+    Extension of the ``.. automodule::`` directive.
+
+     In order to mantain compatibility and extensibility with all the versions of pydantic,
+     it makes sense that this tool uses, rather than the internal pydantic class representation of the class,
+     the interconnected JSON definition of the data structure. From this generic data structure, the tool can
+        generate the documentation in a way that is compatible with the version of pydantic that is being used, or even
+        any generic data structure schema that can be generated from a given class definition.
+
+     The idea is that we can use the ``autoflex`` directive to improve the data structure generated during the
+      `autosummary` process instead of the `automodule` or `autoclass` directive.
+
+
+    Usage
+    -----
+
+    .. code::
+
+        .. autoflex:: my_package.MyClass
+
+    """
+
+    # Directive information
+    has_content: bool = True
+
+    # name: str = "autoflex"
+    # arguments: Any = None
+    # options: Any = None
+    # content: Any = None
+    # lineno: Any = None
+    # content_offset: Any = None
+    # block_text: Any = None
+    # state: Any = None
+    # state_machine: Any = None
+    # reporter: Any = None
+    #
+    # required_arguments: int = 1
+    # optional_arguments: int = 0
+
+    def run(self):
+        print("AutoFlex directive running.")
+        print(self.name)
+        return []

autoflex/directives/flextree.py

@@ -0,0 +1,55 @@
+from sphinx.directives.other import TocTree
+
+
+class FlexTree(TocTree):
+    """
+    Extension of the ``.. toctree::`` sphinx directive.
+
+    Notes
+    -----
+
+    A customizable toctree directive with options to create
+     links with descriptions, custom formatting, and interactive features. Ideally this feature should be developed
+    in an extensible way building on top of the existing ``toctree`` directive.
+
+    Usage
+    -----
+
+    The usage should be broadly compatible with the existing ``.. toctree::`` directive in the structures they represent.
+    However, there is more flexibility in the way the tree is generated and the parameters that can be passed.
+
+    To add descriptions below the given generated links, the following syntax can be used:
+
+    .. code::
+
+        .. flextree::
+            :maxdepth: 2
+
+            mypage1/
+                :description: This is the description of the page.
+            mypage2/
+                :description: This is the description of the page.
+
+
+    """
+
+    # Directive information
+    has_content: bool = True
+
+    # name: str = "autoflex"
+    # arguments: Any = None
+    # options: Any = None
+    # content: Any = None
+    # lineno: Any = None
+    # content_offset: Any = None
+    # block_text: Any = None
+    # state: Any = None
+    # state_machine: Any = None
+    # reporter: Any = None
+    #
+    # required_arguments: int = 1
+    # optional_arguments: int = 0
+
+    def run(self):
+        print("Generating Flextree.")
+        return super().run()

docs/development.rst

@@ -0,0 +1,19 @@
+Development
+===========
+
+The Basics
+-----------
+
+Build the local documentation basically:
+
+.. code::
+
+    poetry run python -m sphinx docs/ _docs/
+
+
+Guidelines
+----------
+
+Note that the development of the project should aim to maximize the usage of the directives developed in this package.
+
+Note that because many of these directives are extending `sphinx`-specific ones, then we want to both mantain compatibility whilst guaranteeing extensibility. One way to approach this is by fixing the corresponding versions of Sphinx we support. We can then build upon the Sphinx directive classes by overwriting their class methods accordingly, depending on what needs to be edited.

docs/directives/autoflex.rst

@@ -0,0 +1,7 @@
+``autoflex``
+============
+
+One of the main complexities we have is that managing `rst` code blocks in docstrings is complicated. It involves manually writing and updating parameter descriptions rather than focusing on the actual docstrings.
+
+When we have multiple classes, and multiple inherited classes, it is hard to keep track of each code block and all the added parameters. For example, it would be possible to manually input parameters at each particular stage. However, it would be nice if this could be extracted directly out of each class declaration automatically and rendered in a nice way.
+

docs/directives/index.rst

@@ -0,0 +1,4 @@
+.. flextree::
+
+    autoflex
+    flextree

docs/directives/overview.rst

@@ -0,0 +1,33 @@
+Usage Overview
+---------------
+
+.. list-table::
+    :header-rows: 1
+
+    * - Extension Command
+      - Brief Description
+      - Specification
+    * - ``flextree``
+      - A customizable toctree directive with options to create links with descriptions, custom formatting, and interactive features.
+      - https://github.com/flexcompute/autoflex/issues/10
+    * - ``autoflex``
+      - Our very extensible, automatic API documentation generator for classes.
+      -
+
+
+.. code:: rst
+
+    .. flextree::
+        :maxdepth: 2
+
+        mypage1/
+            :description: This is the description of the page.
+        mypage2/
+            :description: This is the description of the page.
+
+
+Basic Example:
+
+.. code:: rst
+
+   .. autoflex:: somepackage.MyClass

docs/get_started.rst

@@ -0,0 +1,3 @@
+Get Started
+===========
+

docs/index.rst

@@ -4,21 +4,18 @@
 
 A flexible, nicer way of generating API docs without requiring custom docstrings.
 
-Overview
-========
-
-One of the main complexities we have is that managing `rst` code blocks in docstrings is complicated. It involves manually writing and updating parameter descriptions rather than focusing on the actual docstrings.
+This extension aims to do that.
 
-When we have multiple classes, and multiple inherited classes, it is hard to keep track of each code block and all the added parameters. For example, it would be possible to manually input parameters at each particular stage. However, it would be nice if this could be extracted directly out of each class declaration automatically and rendered in a nice way.
 
-This extension aims to do that.
+.. include:: get_started.rst
+.. include:: directives/overview.rst
 
 Objectives
 ==========
 
 - Improve the API template for `autodoc` which can be limited.
 - For each class, such as `tidy3d` complex classes, properly generate a nicer template of the parameters and methods that extends how autodoc works.
-- Generate an index of each API directive that can be easily searched by corresponding themes like the `sphinx_book_theme`.
+- Generate an index of each API directive that can be easily searched by corresponding themes like the ``sphinx_book_theme``.
 - For inherited classes, have the option to easily define the methods and parameters that we want to generate documentation for.
 - Have the option to generate custom HTML relevant to each class in a way defined by the class docstring.
 - Make sure the docstrings don't interfere with help messages such as ipython, etc. (Maybe explore how to compile relevant docstrings into the help messages).
@@ -27,33 +24,16 @@ Objectives
 
 When we have highly complex classes that have multiple inherited parameters, it is desired to have a clear definition of each specific class and its parameters, types, and defaults. Whilst this can be done manually for an individual class or method, as a project increases in complexity, it is desired to understand the relevant docstrings for each class and method.
 
-Usage
-=====
-
-Build the local documentation basically:
-
-.. code::
-
-    poetry run python -m sphinx docs/ _docs/
-
-
-The idea is that we can use the `autoflex` directive to improve the data structure generated during the `autosummary` process instead of the `automodule` or `autoclass` directive.
-
-Basic Example:
-
-.. code-block:: rst
-
-   .. autoflex:: somepackage.MyClass
-
 
 Indices and tables
 ==================
 
-.. toctree::
+.. flextree::
    :maxdepth: 2
 
-   examples/index
-   examples/demo
+   get_started
+   directives/index
+   development
 
 
 * :ref:`genindex`
@@ -63,5 +43,5 @@ Indices and tables
 Links
 =====
 
-- Source: `<https://github.com/sphinx-contrib/sphinxcontrib-autoflex />`_
-- Bugs: `<https://github.com/sphinx-contrib/sphinxcontrib-autoflex/issues />`_
+- Source: `<https://github.com/flexcompute/autoflex />`_
+- Bugs: `<https://github.com/flexcompute/autoflex/issues />`_

tests/test_directive.py

@@ -1,3 +1 @@
-def test_import():
-    from autoflex import AutoFlexDirective
-    AutoFlexDirective()
+

tests/test_import.py

@@ -0,0 +1 @@
+import autoflex

tests/test_package.py

@@ -1,3 +0,0 @@
-
-def test_import():
-    assert sphinxcontrib.autoflex.install_verification() == True