sphinxnotes.recentupdate

version

1.0b2

copyright

Copyright ©2021 by Shengyu Zhang.

license

BSD, see LICENSE for details.

Get the document update information from git and display it in Sphinx documentation.

This extensions provides a recentupdate directive, which can show recent document update of current Sphinx documentation. The update information is read from Git repository (So you must use Git to manage your documentation). You can customize the update information through generating reStructuredText from Jinja template.

Installation

Download it from official Python Package Index:

$ pip install sphinxnotes-recentupdate

Add extension to conf.py in your sphinx project:

extensions = [
          # …
          'sphinxnotes.recentupdate',
          # …
          ]

Quick Start

1. Installation

2. Add recentupdate directive to your document:

   .. recentupdate::
   

3. Build your document, The directive will be rendered to:

Functionalities

The extension provides a recentupdate directive:

.. recentupdate:: [count]

   [jinja template]

count

The optional argument of directive is the count of recent “revisions” you want to show. Revision is a git commit which contains document changes.

If no count given, value of ⚙️recentupdate_count is used.

template

The optional content of directive is a jinja template for generating reStructuredText, in the template you can access Variables named {{ revisions }}.

Beside, You can use Builtin Filters and Filters provided by extensions.

If no template given, value of ⚙️recentupdate_template is used.

Variables

All available variables:

{{ revisions }}

{{ revisions }} is an an array of revisions. The length of array is determined by the argument of`recentupdate <Functionalities>`_ directive.

Here is the schema of array element:

class recentupdate.Revision

Revision represents a git commit which contains document changes.

__init__(message, author, date, addition, modification, deletion)

Parameters

• message (str) –

• author (str) –

• date (datetime.datetime) –

• addition (List[str]) –

• modification (List[str]) –

• deletion (List[str]) –

Return type

None

addition: List[str]

List of docname, corresponding to files which are modified

author: str

Git commit author

date: datetime.datetime

Git commit author date

deletion: List[str]

List of docname, corresponding to files which are deleted

message: str

Git commit message

modification: List[str]

List of docname, corresponding to files which are newly added

Filters

strftime

Convert a datetime.datetime to string in given format.

If no format given, use value of ⚙️recentupdate_date_format.

It is used in default template.

roles

Convert a list of string to list of reStructuredText roles.

{{ ['foo', 'bar'] | roles("doc") }} produces [':doc:`foo`', ':doc:`bar`'].

It is used in default template.

Configuration

The extension provides the following configuration:

recentupdate_count

Type

int

Default

10

The default count of recent revisions. See Functionalities.

recentupdate_template

Type

str

Default

see below

The default Jinja template of update information. See Functionalities.

Here is the default value:

{% for r in revisions %}
{{ r.date | strftime }}
  :Author: {{ r.author }}
  :Message: {{ r.message }}

  {% if r.modification %}
  - Modified {{ r.modification | roles("doc") | join(", ") }}
  {% endif %}
  {% if r.addition %}
  - Added {{ r.addition | roles("doc") | join(", ") }}
  {% endif %}
  {% if r.deletion %}
  - Deleted {{ r.deletion | join(", ") }}
  {% endif %}
{% endfor %}

recentupdate_date_format

Type

str

Default

"%Y-%m-%dT"

The default date format of strftime filter.

recentupdate_exclude_path

Type

List[str]

Default

[]

A list of path that should be excluded when looking for file changes.

recentupdate_exclude_commit

Type

List[str]

Default

["skip-recentupdate"]

A list of commit message pattern that should be excluded when looking for file changes.

Change Log

2021-12-06 1.0a0

Release alpha version.