Snippet update

Snip plugin for Sphinx conf.py. Replaces snippet containing variables:

  • copyright

  • version

  • release

  • release_date

drain_swamp.snippet_sphinx_conf.__all__: tuple[str] = ("SnipSphinxConf", "entrypoint_name")

Module exports

drain_swamp.snippet_sphinx_conf.entrypoint_name: str = "drain-swamp"

Will use this entrypoint. In pyproject.toml, [tool.drain-swamp]

drain_swamp.snippet_sphinx_conf._logger: logging.Logger

Module level logger

class drain_swamp.snippet_sphinx_conf.SnipSphinxConf(path=None)

Snip plugin for Sphinx conf.py snippet which sets:

  • copyright

  • version

  • release

  • release_date

This is done for every tagged release

Sphinx docs folder name is either doc or docs. If it’s something else, complain!

DOC_FOLDERS: tuple[str, str] = ("doc", "docs")

Possible Sphinx doc folder basename

Variables:

path (pathlib.Path | None) – Default None. absolute path to package base folder. If None, use current working folder

Raises:
property SV: SemVersion | None

Getter for SemVersion instance.

Returns:

After call to contents, SemVersion instance is available

Return type:

SemVersion | None

property author_name_left: str | None

Getter for author name, but just the left portion.

In Japanese, this is the full name. Otherwise would be the first name

Used within regex to replace copyright notice

Returns:

Author name left. If contents yet to be called will be None

Return type:

str | None

contents(kind, package_name, copyright_start_year)

Create the snippet for Sphinx conf.py.

This will set:

  • copyright

  • version

  • release

  • release_date

This is done for every tagged release

Sphinx docs folder name is either doc or docs. If it’s something else, complain!

Parameters:

  • kind (str) – Explicit version str or “current”|”now” or “tag”. tag for the latest tagged version. Current for the latest version which is probably the development version

  • package_name (str) – Can contain either hyphen or underscore. Both will work. From the package name can get the author name and email address. Only interested in the author name

  • copyright_start_year (str) – This packages copyright start year

Raises:

  • AssertionError – Expected Sphinx docs folder to be either doc/ or docs/

  • ValueError – Explicit version str is invalid

classmethod now()

Current datetime.

Returns:

current datetime

Return type:

datetime.datetime

classmethod now_to_str(strftime_str)

Format datetime now.

Parameters:

strftime_str (str) – format str

Returns:

datetime formatted with strftime format

Return type:

str

Raises:
property path_abs

Absolute path to doc/conf.py or docs/conf.py.

Returns:

package base folder

Return type:

pathlib.Path

path_abs_init()

Using from package base path or cwd, find doc/ or docs/ folder absolute path.

Raises:
property path_cwd

Get package base folder.

Returns:

package base folder

Return type:

pathlib.Path

replace(snippet_co=None)

In a Sphinx conf.py file, for a given snippet, replace contents.

Parameters:

snippet_co (str | None) – Default None. id of snippet within Sphinx conf.py. If None, that snippet better not have an id or there be other snippets in that file

Returns:

  • VALIDATE_FAIL – Invalid snippet

  • NOMATCH – no matching snippet with snippet_co

  • NO_CHANGE – no replacement occurred

  • REPLACED – replaced contents

Return type:

drain_swamp_snippet.ReplaceResult