Add mermaid-inheritance

.travis.yml

@@ -6,7 +6,5 @@ python:
 sudo: false
 cache: pip
 install:
- - pip install -r docs/requirements.txt
- - pip install pytest
- - pip install -e .
-script: pytest
+ - pip install -e .[dev]
+script: pytest && pytest --check-links --check-links-ignore "https://travis-ci.com/*"

README.rst

@@ -82,6 +82,52 @@ Or directly the module::
 
 .. autoclasstree:: sphinx.util
 
+And alternative to `autoclasstree` directive is `mermaid-inheritance`. That directive mimics exactly the
+official `inheritance_diagram <https://www.sphinx-doc.org/en/master/usage/extensions/inheritance.html>`_ 
+extension but uses mermaid JS instead of graphviz to include the inheritance diagrams.
+
+It adds this directive::
+
+    .. mermaid-inheritance::
+
+This directive has one or more arguments, each giving a module or class name. Class names can be unqualified; 
+in that case they are taken to exist in the currently described module.
+
+For each given class, and each class in each given module, the base classes are determined. Then, from all classes 
+and their base classes, a graph is generated which is then rendered via the ``mermaid`` extension to a directed graph.
+
+This directive supports an option called ``parts`` that, if given, must be an integer, advising the directive 
+to keep that many dot-separated parts in the displayed names (from right to left). For example, ``parts=1``
+will only display class names, without the names of the modules that contain them.
+
+The directive also supports a ``private-bases`` flag option; if given, private base classes (those whose name 
+starts with ``_``) will be included.
+
+You can use ``caption`` option to give a caption to the diagram.
+
+It also supports a ``top-classes`` option which requires one or more class names separated by comma. If specified 
+inheritance traversal will stop at the specified class names. 
+
+For example::
+
+    .. mermaid-inheritance:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+
+.. mermaid-inheritance:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+
+.. note::
+
+    ``.`` are replaced by ``_`` in class name because mermaidJS does not allow them.
+
+To stop the diagram at ``SphinxDirective`` and only display the class name::
+
+    .. mermaid-inheritance:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+        :top-classes: sphinx.util.docutils.SphinxDirective
+        :parts: 1
+
+
+.. mermaid-inheritance:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+   :top-classes: sphinx.util.docutils.SphinxDirective
+   :parts: 1
 
 Installation
 ------------
@@ -96,7 +142,9 @@ Then add ``sphinxcontrib.mermaid`` in ``extensions`` list of your project's ``co
 
     extensions = [
         ...,
-        'sphinxcontrib.mermaid'
+        'sphinxcontrib.mermaid',
+        # Optional if you want the inheritance graphs
+        'sphinxcontrib.mermaid-inheritance',
     ]
 
 
@@ -149,7 +197,7 @@ Config values
 
 ``mermaid_params``
 
-   For individual parameters, a list of parameters can be added. Refer to `<https://github.com/mermaidjs/mermaid.cli#options>`_.
+   For individual parameters, a list of parameters can be added. Refer to `<https://github.com/mermaid-js/mermaid-cli#options>`_.
    Examples::
 
       mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']
@@ -159,7 +207,7 @@ Config values
 ``mermaid_sequence_config``
 
     Allows overriding the sequence diagram configuration. It could be useful to increase the width between actors. It **needs to be a json file**
-    Check options in the `documentation <https://mermaid-js.github.io/mermaid/#/mermaidAPI?id=configuration>`_
+    Check options in the `documentation <https://mermaid-js.github.io/mermaid/#/n00b-syntaxReference?id=configuration>`_
 
 ``mermaid_verbose``
 

docs/conf.py

@@ -31,35 +31,33 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinxcontrib.mermaid'
-]
+extensions = ["sphinxcontrib.mermaid", "sphinxcontrib.mermaid_inheritance"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'sphinxcontrib-mermaid'
-copyright = '2017-2021, Martín Gaitán'
-author = 'Martín Gaitán'
+project = "sphinxcontrib-mermaid"
+copyright = "2017-2021, Martín Gaitán"
+author = "Martín Gaitán"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = ""
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -72,10 +70,10 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
@@ -86,7 +84,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "alabaster"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -97,16 +95,16 @@
 # 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"]
 
 html_js_files = [
-    'js/custom.js',
+    "js/custom.js",
 ]
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'sphinxcontrib-mermaiddoc'
+htmlhelp_basename = "sphinxcontrib-mermaiddoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -115,15 +113,12 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -133,8 +128,13 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'sphinxcontrib-mermaid.tex', 'sphinxcontrib-mermaid documentation',
-     'Martín Gaitán', 'manual'),
+    (
+        master_doc,
+        "sphinxcontrib-mermaid.tex",
+        "sphinxcontrib-mermaid documentation",
+        "Martín Gaitán",
+        "manual",
+    ),
 ]
 
 
@@ -143,8 +143,13 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'sphinxcontrib-mermaid', 'sphinxcontrib-mermaid documentation',
-     [author], 1)
+    (
+        master_doc,
+        "sphinxcontrib-mermaid",
+        "sphinxcontrib-mermaid documentation",
+        [author],
+        1,
+    )
 ]
 
 
@@ -154,10 +159,13 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'sphinxcontrib-mermaid', 'sphinxcontrib-mermaid documentation',
-     author, 'sphinxcontrib-mermaid', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "sphinxcontrib-mermaid",
+        "sphinxcontrib-mermaid documentation",
+        author,
+        "sphinxcontrib-mermaid",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
-
-
-

docs/index.rst

@@ -1,4 +1,4 @@
-.. Sphinxcontrib-mesmaid demo documentation master file, created by
+.. Sphinxcontrib-mermaid demo documentation master file, created by
    sphinx-quickstart on Sun Apr 23 13:10:20 2017.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.

setup.py

@@ -3,9 +3,9 @@
 import io
 from setuptools import setup, find_packages
 
-readme = io.open('README.rst', encoding="utf-8").read()
-changes = io.open('CHANGELOG.rst', encoding="utf-8").read()
-version = '0.7.1'
+readme = io.open("README.rst", encoding="utf-8").read()
+changes = io.open("CHANGELOG.rst", encoding="utf-8").read()
+version = "0.7.1"
 
 
 def long_description():
@@ -25,40 +25,53 @@ def remove_block(text, token, margin=0):
     readme_ = remove_block(readme, ".. mermaid::", margin=2)
     readme_ = remove_block(readme_, ".. autoclasstree::")
     readme_ = remove_block(readme_, ".. autoclasstree::")
+    readme_ = remove_block(readme_, ".. mermaid-inheritance::")
+    readme_ = remove_block(readme_, ".. mermaid-inheritance::")
     readme_ = remove_block(readme_, ".. versionchanged::")
     return "{}\n\n{}".format(readme_, changes)
 
 
 setup(
-    name='sphinxcontrib-mermaid',
+    name="sphinxcontrib-mermaid",
     version=version,
-    url='https://github.com/mgaitan/sphinxcontrib-mermaid',
-    download_url='https://pypi.python.org/pypi/sphinxcontrib-mermaid',
-    license='BSD',
-    author=u'Martín Gaitán',
-    author_email='gaitan@gmail.com',
-    description='Mermaid diagrams in yours Sphinx powered docs',
+    url="https://github.com/mgaitan/sphinxcontrib-mermaid",
+    download_url="https://pypi.python.org/pypi/sphinxcontrib-mermaid",
+    license="BSD",
+    author=u"Martín Gaitán",
+    author_email="gaitan@gmail.com",
+    description="Mermaid diagrams in yours Sphinx powered docs",
     long_description=long_description(),
     classifiers=[
-        'Development Status :: 4 - Beta',
-        'Environment :: Console',
-        'Environment :: Web Environment',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: BSD License',
-        'Operating System :: OS Independent',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
-        'Programming Language :: Python :: 3.8',
-        'Programming Language :: Python :: 3.9',
-        'Programming Language :: Python :: Implementation :: CPython',
-        'Programming Language :: Python :: Implementation :: PyPy',
-        'Topic :: Documentation',
-        'Topic :: Utilities',
+        "Development Status :: 4 - Beta",
+        "Environment :: Console",
+        "Environment :: Web Environment",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: BSD License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: Implementation :: CPython",
+        "Programming Language :: Python :: Implementation :: PyPy",
+        "Topic :: Documentation",
+        "Topic :: Utilities",
     ],
-    platforms='any',
+    platforms="any",
     packages=find_packages(),
     include_package_data=True,
-    namespace_packages=['sphinxcontrib'],
+    namespace_packages=["sphinxcontrib"],
+    python_requires=">=3.6",
+    install_requires=["sphinx>=3.2.1"],
+    extras_require={
+        "dev": [
+            "black",
+            "pytest>=6.0",
+            "pytest-check-links>=0.5",
+            "myst-parser>=0.15.1",
+        ],
+        "doc": ["myst-parser>=0.15.1"],
+    },
 )

sphinxcontrib/__init__.py

@@ -10,4 +10,4 @@
     :license: BSD, see LICENSE for details.
 """
 
-__import__('pkg_resources').declare_namespace(__name__)
+__import__("pkg_resources").declare_namespace(__name__)

sphinxcontrib/autoclassdiag.py

@@ -21,7 +21,9 @@ def get_classes(*cls_or_modules, strict=False):
 
         elif inspect.ismodule(obj):
             for obj_ in obj.__dict__.values():
-                if inspect.isclass(obj_) and (not strict or obj_.__module__.startswith(obj.__name__)):
+                if inspect.isclass(obj_) and (
+                    not strict or obj_.__module__.startswith(obj.__name__)
+                ):
                     yield obj_
         else:
             raise MermaidError("%s is not a class nor a module" % cls_or_module)
@@ -33,7 +35,7 @@ def class_diagram(*cls_or_modules, full=False, strict=False, namespace=None):
     def get_tree(cls):
         for base in cls.__bases__:
 
-            if base.__name__ == 'object':
+            if base.__name__ == "object":
                 continue
             if namespace and not base.__module__.startswith(namespace):
                 continue
@@ -45,14 +47,12 @@ def get_tree(cls):
         get_tree(cls)
 
     return "classDiagram\n" + "\n".join(
-            "  %s <|-- %s" % (a, b)
-                for a, b in inheritances
-            )
+        "  %s <|-- %s" % (a, b) for a, b in inheritances
+    )
 
 
 if __name__ == "__main__":
 
-
     class A:
         pass
 
@@ -72,5 +72,3 @@ class E(C1):
         pass
 
     print(class_diagram("__main__.D", "__main__.E", full=True))
-
-