add git-shortlog-authors directive

README.md

@@ -10,10 +10,21 @@ This package should be used in all sphinx projects under the [@deepmodeling](htt
 
 ## How to use it
 
+### Setup
+
 Add `deepmodeling_sphinx` to the requirements, as well as the `extensions` of `conf.py`:
 
 ```py
 extensions = [
     'deepmodeling_sphinx',
 ]
 ```
+
+### Render list of authors
+
+The following directive can be used to render list of authors from `git shortlog`:
+
+```rst
+.. git-shortlog-authors::
+
+```

deepmodeling_sphinx/__init__.py

@@ -1,3 +1,12 @@
-from .inject import setup
+from typing import Any, Dict
+from sphinx.application import Sphinx
+
+from .inject import setup as setup_inject
+from .authors import setup as setup_authors
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    setup_inject(app)
+    setup_authors(app)
+    return {'parallel_read_safe': True}
 
 __all__ = ['setup']

deepmodeling_sphinx/authors.py

@@ -0,0 +1,56 @@
+"""A directive to list all authors from git-shortlog."""
+
+import os
+import subprocess
+from typing import Any, Dict, Iterator
+
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+
+
+def git_shortlog() -> str:
+    """Return git-shortlog output as a string.
+
+    Returns
+    -------
+    str
+        Git-shortlog output.
+    """
+    if os.environ.get("READTHEDOCS", None) == "True":
+        # check if it shallow clone
+        output_git_rev_parse = subprocess.check_output(["git", "rev-parse", "--is-shallow-repository"]).decode('utf-8').strip()
+        if output_git_rev_parse == "true":
+            # fetch full history
+            subprocess.check_output(["git", "fetch", "--unshallow"])
+    return subprocess.check_output(['git', 'shortlog', 'HEAD', '-s']).decode('utf-8')
+
+
+def get_authors() -> Iterator[str]:
+    """Yields authors from git-shortlog.
+
+    Yields
+    ------
+    str
+        Author name.
+    """
+    shortlog_text = git_shortlog()
+    for line in shortlog_text.splitlines():
+        yield line.split('\t')[1]
+
+
+class AuthorsDirective(SphinxDirective):
+    """authors directive."""
+    has_content = False
+    option_spec = dict(
+    )
+
+
+    def run(self):
+        """Run directive."""
+        authors = ["* " + author for author in get_authors()]
+        self.state_machine.insert_input(authors, "")
+        return []
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_directive(name="git-shortlog-authors", cls=AuthorsDirective)
+    return {'parallel_read_safe': True}

docs/conf.py

@@ -1,6 +1,6 @@
 from datetime import date
 
-project = 'DeepModeling'
+project = 'deepmodeling_sphinx'
 copyright = '2022-%d, DeepModeling' % date.today().year
 author = 'DeepModeling'
 

docs/credits.rst

@@ -0,0 +1,4 @@
+Authors
+=======
+
+.. git-shortlog-authors::

docs/index.rst

@@ -1,6 +1,20 @@
 .. include:: ../README.md
    :parser: myst_parser.sphinx_
 
+Others
+------
+
+.. toctree::
+   :hidden:
+
+   Summary <self>
+
+
+.. toctree::
+   :titlesonly:
+
+   credits
+
 ------------------