Skip to content

Commit 7259ca2

Browse files
tomschrtomschr
authored
Fix #16: Implement metadata functionality (#42)
* Implement "docbuild metadata" * Add more tests * Catch ValueError in validate_doctypes callback Fix test case due to ValueError * Document subcommand `docbuild metadata`
1 parent f6bc535 commit 7259ca2

16 files changed

Lines changed: 1014 additions & 35 deletions

File tree

‎changelog.d/16.feature.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Implement metadata from a ``daps metadata`` command.

‎docs/source/reference/_autoapi/docbuild/cli/cmd_metadata/index.rst‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
docbuild.cli.cmd_metadata
2+
=========================
3+
4+
.. py:module:: docbuild.cli.cmd_metadata
5+
6+
.. autoapi-nested-parse::
7+
8+
Extracts metadata from deliverables.
9+
10+
11+
12+
Functions
13+
---------
14+
15+
.. autoapisummary::
16+
17+
docbuild.cli.cmd_metadata.get_deliverable_from_doctype
18+
docbuild.cli.cmd_metadata.process_deliverable
19+
docbuild.cli.cmd_metadata.process_doctype
20+
docbuild.cli.cmd_metadata.process
21+
docbuild.cli.cmd_metadata.metadata
22+
23+
24+
Package Contents
25+
----------------
26+
27+
.. py:function:: get_deliverable_from_doctype(root: lxml.etree._ElementTree, context: docbuild.cli.context.DocBuildContext, doctype: docbuild.models.doctype.Doctype) -> list[docbuild.models.deliverable.Deliverable]
28+
29+
Get deliverable from doctype.
30+
31+
:param root: The stitched XML node containing configuration.
32+
:param context: The DocBuildContext containing environment configuration.
33+
:param doctype: The Doctype object to process.
34+
:return: A list of deliverables for the given doctype.
35+
36+
37+
.. py:function:: process_deliverable(deliverable: docbuild.models.deliverable.Deliverable, *, repo_dir: pathlib.Path, temp_repo_dir: pathlib.Path, base_cache_dir: pathlib.Path, meta_cache_dir: pathlib.Path, dapstmpl: str) -> bool
38+
:async:
39+
40+
41+
Process a single deliverable.
42+
43+
This function creates a temporary clone of the deliverable's repository,
44+
checks out the correct branch, and then executes the DAPS command to
45+
generate metadata.
46+
47+
:param deliverable: The Deliverable object to process.
48+
:param repo_dir: The permanent repo path taken from the env
49+
config ``paths.repo_dir``
50+
:param temp_repo_dir: The temporary repo path taken from the env
51+
config ``paths.temp_repo_dir``
52+
:param base_cache_dir: The base path of the cache directory taken
53+
from the env config ``paths.base_cache_dir``
54+
:param meta_cache_dir: The ath of the metadata directory taken
55+
from the env config ``paths.meta_cache_dir``
56+
:param dapstmp: A template string with the daps command and potential
57+
placeholders
58+
:return: True if successful, False otherwise.
59+
:raises ValueError: If required configuration paths are missing.
60+
61+
62+
.. py:function:: process_doctype(root: lxml.etree._ElementTree, context: docbuild.cli.context.DocBuildContext, doctype: docbuild.models.doctype.Doctype) -> bool
63+
:async:
64+
65+
66+
Process the doctypes and create metadata files.
67+
68+
:param root: The stitched XML node containing configuration.
69+
:param context: The DocBuildContext containing environment configuration.
70+
:param doctypes: A tuple of Doctype objects to process.
71+
72+
73+
.. py:function:: process(context: docbuild.cli.context.DocBuildContext, doctypes: tuple[docbuild.models.doctype.Doctype]) -> int
74+
:async:
75+
76+
77+
Asynchronous function to process metadata retrieval.
78+
79+
:param context: The DocBuildContext containing environment configuration.
80+
:param xmlfiles: A tuple or iterator of XML file paths to validate.
81+
:raises ValueError: If no envconfig is found or if paths are not
82+
configured correctly.
83+
:return: 0 if all files passed validation, 1 if any failures occurred.
84+
85+
86+
.. py:function:: metadata(ctx: click.Context, doctypes: tuple[docbuild.models.doctype.Doctype]) -> None
87+
88+
Subcommand to create metadata files.
89+
90+
:param ctx: The Click context object.
91+
92+

‎docs/source/reference/_autoapi/docbuild/cli/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Submodules
2727
/reference/_autoapi/docbuild/cli/cmd_build/index
2828
/reference/_autoapi/docbuild/cli/cmd_c14n/index
2929
/reference/_autoapi/docbuild/cli/cmd_cli/index
30+
/reference/_autoapi/docbuild/cli/cmd_metadata/index
3031
/reference/_autoapi/docbuild/cli/cmd_repo/index
3132
/reference/_autoapi/docbuild/cli/cmd_validate/index
3233
/reference/_autoapi/docbuild/cli/config/index

‎docs/source/reference/_autoapi/docbuild/utils/contextmgr/index.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,18 +33,18 @@ Functions
3333
Module Contents
3434
---------------
3535

36-
.. py:function:: make_timer(name: str, method: collections.abc.Callable = time.perf_counter)
36+
.. py:function:: make_timer(name: str, method: collections.abc.Callable[[], float] = time.perf_counter) -> collections.abc.Callable[[], contextlib.AbstractContextManager[TimerData]]
3737
3838
Create independant context managers to measure elapsed time.
3939

4040
Each timer is independent and can be used in a context manager.
4141
The name is used to identify the timer.
4242

4343
:param name: Name of the timer.
44-
:param method: Method to use for measuring time, defaults
45-
to :func:`time.perf_counter`.
46-
:return: A context manager that yields a dictionary with start, end,
47-
and elapsed time.
44+
:param method: A callable that returns a float, used for measuring time.
45+
Defaults to :func:`time.perf_counter`.
46+
:return: A callable that returns a context manager. The context manager
47+
yields a :class:`TimerData` object.
4848

4949
.. code-block:: python
5050

‎docs/source/user/config.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. _configuring-docbuild:
1+
.. _config-docbuild:
22

33
Configuring the Tool
44
---------------------

‎docs/source/user/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ User Guide
1212
build
1313
validate
1414
clone
15+
metadata

‎docs/source/user/install.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ To install the docbuild tool, follow these steps:
99

1010
#. :ref:`get-xml-config` - Get the XML configuration files required for building documentation.
1111

12-
#. :ref:`configuring-docbuild` - Configure the docbuild tool to suit your needs.
12+
#. :ref:`config-docbuild` - Configure the docbuild tool to suit your needs.
1313

1414

1515
.. _prepare-installation:

‎docs/source/user/metadata.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Creating Metadata
2+
=================
3+
4+
The :command:`docbuild metadata` subcommand is used to create metadata from a :command:`daps metadata` call.
5+
6+
7+
.. code-block:: shell
8+
:caption: Synopsis of :command:`docbuild metadata`
9+
10+
docbuild metadata [OPTIONS] [DOCTYPES]...
11+
12+
The process does this:
13+
14+
#. Determine the :term:`doctypes <Doctype>` from the command line.
15+
#. Iterate over all :term:`deliverables <Deliverable>` of the doctypes.
16+
#. For each deliverable, call :command:`daps metadata` to create the metadata.
17+
#. Store the metadata in the cache directory of the deliverable. The cache directory is defined in the env configuration file under ``paths.meta_cache_dir``, see also section :ref:`config-docbuild`.

‎src/docbuild/cli/callback.py‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
1-
# --- Callback Function ---
1+
import logging
2+
23
import click
34
from pydantic import Field, ValidationError
45

56
from ..models.doctype import Doctype
67
from ..utils.merge import merge_doctypes
78

9+
#
10+
log = logging.getLogger(__name__)
11+
812

913
def validate_doctypes(
1014
ctx: click.Context,
@@ -32,9 +36,16 @@ def validate_doctypes(
3236
for doctype_str in doctypes:
3337
try:
3438
doctype = Doctype.from_str(doctype_str)
35-
click.echo(f'Got {doctype}')
3639
processed_data.append(doctype)
3740

41+
except ValueError as err:
42+
click.secho(
43+
f"ERROR: Invalid doctype string '{doctype_str}': {err}",
44+
fg='red',
45+
err=True,
46+
)
47+
raise click.Abort(err) from err
48+
3849
except ValidationError as err:
3950
for error in err.errors():
4051
field = error['loc'][0]

‎src/docbuild/cli/cmd_cli.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
from ..logging import setup_logging
1919
from .cmd_build import build
2020
from .cmd_c14n import c14n
21+
from .cmd_metadata import metadata
2122
from .cmd_repo import repo
2223
from .cmd_validate import validate
2324
from .config import config
@@ -142,4 +143,5 @@ def cli(
142143
cli.add_command(c14n)
143144
cli.add_command(config)
144145
cli.add_command(repo)
146+
cli.add_command(metadata)
145147
cli.add_command(validate)

0 commit comments

Comments
 (0)