diff --git a/README.md b/README.md index af880cf..ca853ef 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ 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 @@ -17,3 +19,12 @@ 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:: + +``` diff --git a/deepmodeling_sphinx/__init__.py b/deepmodeling_sphinx/__init__.py index b5c4736..1fe10e2 100644 --- a/deepmodeling_sphinx/__init__.py +++ b/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'] diff --git a/deepmodeling_sphinx/authors.py b/deepmodeling_sphinx/authors.py new file mode 100644 index 0000000..1d650d7 --- /dev/null +++ b/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} diff --git a/docs/conf.py b/docs/conf.py index 89c105e..e82aef1 100644 --- a/docs/conf.py +++ b/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' diff --git a/docs/credits.rst b/docs/credits.rst new file mode 100644 index 0000000..f8cfc84 --- /dev/null +++ b/docs/credits.rst @@ -0,0 +1,4 @@ +Authors +======= + +.. git-shortlog-authors:: diff --git a/docs/index.rst b/docs/index.rst index 547901a..5692efc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,20 @@ .. include:: ../README.md :parser: myst_parser.sphinx_ +Others +------ + +.. toctree:: + :hidden: + + Summary + + +.. toctree:: + :titlesonly: + + credits + ------------------