Skip to content

Commit

Permalink
List testing (#3)
Browse files Browse the repository at this point in the history 
* adding list utilities, md namespace

* minor readme correction

* sprucing up readme with new syntactic constructs

* adding better docs to env
  • Loading branch information
@dsillman2000
dsillman2000 authored Nov 24, 2023
1 parent 9fede40 commit a96ead0
Show file tree
Hide file tree
Showing 9 changed files with 861 additions and 67 deletions.
25 changes: 17 additions & 8 deletions .metadock/content_schematics/repo_readme.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -184,18 +184,27 @@ content_schematics:
init:
description: Used to initialize a fresh Metadock project in a folder which does not currently have one.
usage: metadock [-p PROJECT_DIR] init
python_interface:
method_name: metadock.Metadock.init
signature: (Path | str) -> metadock.Metadock
python_interface: *python_interface_init

validate:
description: Used to validate the structure of an existing Metadock project.
usage: metadock [-p PROJECT_DIR] validate
python_interface:
method_name: metadock.Metadock.validate
signature: () -> metadock.engine.MetadockProjectValidationResult


python_interface: *python_interface_validate

build:
description: Used to build a Metadock project, rendering some or all documents.
usage: metadock [-p PROJECT_DIR] build [-s SCHEMATIC_GLOBS [SCHEMATIC_GLOBS ...]] [-t TEMPLATE_GLOBS [TEMPLATE_GLOBS ...]]
python_interface: *python_interface_build

list:
description: Used to list all recognized documents which can be generated from a given selection.
usage: metadock [-p PROJECT_DIR] list [-s SCHEMATIC_GLOBS [SCHEMATIC_GLOBS ...]] [-t TEMPLATE_GLOBS [TEMPLATE_GLOBS ...]]
python_interface: *python_interface_list

clean:
description: Used to clean the generated_documents directory for the Metadock project.
usage: metadock [-p PROJECT_DIR] clean
python_interface: *python_interface_clean

# Target formats
target_formats:
Expand Down
83 changes: 78 additions & 5 deletions .metadock/generated_documents/README.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ <h2>Quick Intro</h2>
<p>The root of your project is expected to have a <code>.metadock</code> folder, which can be generated from the CLI using
<code>metadock init</code>.</p>
<h2>Basic CLI Usage</h2>
<p>The <code>metadock</code> CLI, installed using <code>pip install metadock</code>, has five basic commands, spelled out in the help message:</p>
<p>The <code>metadock</code> CLI, installed using <code>pip install metadock</code>, has 5 basic commands, spelled out in the help message:</p>
<pre><code class="language-sh">usage: metadock [-h] [-p PROJECT_DIR] {init,validate,build,list,clean} ...

Generates and formats Jinja documentation templates from yaml sources.
Expand All @@ -44,6 +44,82 @@ <h2>Basic CLI Usage</h2>
-p PROJECT_DIR, --project-dir PROJECT_DIR
Project directory containing a .metadock directory.
</code></pre>
<p>Each of the commands supports a programmatic invocation from the <code>metadock.Metadock</code> class via a Python interface.</p>
<details>
<summary>
<code>metadock init</code>
</summary>
<ul>
<li><strong>Description</strong>: Used to initialize a fresh Metadock project in a folder which does not currently have one.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] init</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.init</code></li>
<li>Signature: <code>(Path | str) -&gt; metadock.Metadock</code></li>
</ul>
</li>
</ul>
</details>
<details>
<summary>
<code>metadock validate</code>
</summary>
<ul>
<li><strong>Description</strong>: Used to validate the structure of an existing Metadock project.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] validate</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.validate</code></li>
<li>Signature: <code>() -&gt; metadock.engine.MetadockProjectValidationResult</code></li>
</ul>
</li>
</ul>
</details>
<details>
<summary>
<code>metadock build</code>
</summary>
<ul>
<li><strong>Description</strong>: Used to build a Metadock project, rendering some or all documents.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] build [-s SCHEMATIC_GLOBS [SCHEMATIC_GLOBS ...]] [-t TEMPLATE_GLOBS [TEMPLATE_GLOBS ...]]</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.build</code></li>
<li>Signature: <code>(list[str], list[str]) -&gt; metadock.engine.MetadockProjectBuildResult</code></li>
</ul>
</li>
</ul>
</details>
<details>
<summary>
<code>metadock list</code>
</summary>
<ul>
<li><strong>Description</strong>: Used to list all recognized documents which can be generated from a given selection.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] list [-s SCHEMATIC_GLOBS [SCHEMATIC_GLOBS ...]] [-t TEMPLATE_GLOBS [TEMPLATE_GLOBS ...]]</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.list</code></li>
<li>Signature: <code>(list[str], list[str]) -&gt; metadock.engine.MetadockProjectListResult</code></li>
</ul>
</li>
</ul>
</details>
<details>
<summary>
<code>metadock clean</code>
</summary>
<ul>
<li><strong>Description</strong>: Used to clean the generated_documents directory for the Metadock project.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] clean</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.clean</code></li>
<li>Signature: <code>() -&gt; None</code></li>
</ul>
</li>
</ul>
</details>
<h2>Example Usage</h2>
<p>In the example above, we can imagine the content of our template, <code>gitlab_mr_template.md</code>, to look something like this:</p>
<pre><code class="language-md">{%- set jira_project_name = jira.get(&#x27;project_name&#x27;) -%}
Expand Down Expand Up @@ -161,13 +237,10 @@ <h1>[IGDP-13] Adding software version as hard requirement for staging</h1>
<li>Generates the given template, parses it into a markdown document, and then generates HTML from it.</li>
</ul>
</li>
<li>
Anything else, e.g. <code>txt</code>, <code>sql</code> or <code>py</code><ul>
<li>Anything else, e.g. <code>txt</code>, <code>sql</code> or <code>py</code></li>
<li>Generates the given template as plaintext, and adds the given string as a file extension, e.g. <code>.txt</code>, <code>.sql</code> or
<code>.py</code>.</li>
</ul>
</li>
</ul>
<h2>Acknowledgements</h2>
<p>Author:</p>
<ul>
Expand Down
95 changes: 92 additions & 3 deletions .metadock/generated_documents/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The root of your project is expected to have a `.metadock` folder, which can be

## Basic CLI Usage

The `metadock` CLI, installed using `pip install metadock`, has five basic commands, spelled out in the help message:
The `metadock` CLI, installed using `pip install metadock`, has 5 basic commands, spelled out in the help message:

```sh
usage: metadock [-h] [-p PROJECT_DIR] {init,validate,build,list,clean} ...
Expand All @@ -56,6 +56,95 @@ options:
Project directory containing a .metadock directory.
```

Each of the commands supports a programmatic invocation from the `metadock.Metadock` class via a Python interface.

<details>
<summary>
<code>metadock init</code>
</summary>

<ul>
<li><strong>Description</strong>: Used to initialize a fresh Metadock project in a folder which does not currently have one.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] init</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.init</code></li>
<li>Signature: <code>(Path | str) -&gt; metadock.Metadock</code></li>
</ul>
</li>
</ul>

</details>
<details>
<summary>
<code>metadock validate</code>
</summary>

<ul>
<li><strong>Description</strong>: Used to validate the structure of an existing Metadock project.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] validate</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.validate</code></li>
<li>Signature: <code>() -&gt; metadock.engine.MetadockProjectValidationResult</code></li>
</ul>
</li>
</ul>

</details>
<details>
<summary>
<code>metadock build</code>
</summary>

<ul>
<li><strong>Description</strong>: Used to build a Metadock project, rendering some or all documents.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] build [-s SCHEMATIC_GLOBS [SCHEMATIC_GLOBS ...]] [-t TEMPLATE_GLOBS [TEMPLATE_GLOBS ...]]</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.build</code></li>
<li>Signature: <code>(list[str], list[str]) -&gt; metadock.engine.MetadockProjectBuildResult</code></li>
</ul>
</li>
</ul>

</details>
<details>
<summary>
<code>metadock list</code>
</summary>

<ul>
<li><strong>Description</strong>: Used to list all recognized documents which can be generated from a given selection.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] list [-s SCHEMATIC_GLOBS [SCHEMATIC_GLOBS ...]] [-t TEMPLATE_GLOBS [TEMPLATE_GLOBS ...]]</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.list</code></li>
<li>Signature: <code>(list[str], list[str]) -&gt; metadock.engine.MetadockProjectListResult</code></li>
</ul>
</li>
</ul>

</details>
<details>
<summary>
<code>metadock clean</code>
</summary>

<ul>
<li><strong>Description</strong>: Used to clean the generated_documents directory for the Metadock project.</li>
<li><strong>Usage</strong>: <code>metadock [-p PROJECT_DIR] clean</code></li>
<li>
<strong>Python interface</strong>:<ul>
<li>Name: <code>metadock.Metadock.clean</code></li>
<li>Signature: <code>() -&gt; None</code></li>
</ul>
</li>
</ul>

</details>


## Example Usage

In the example above, we can imagine the content of our template, `gitlab_mr_template.md`, to look something like this:
Expand Down Expand Up @@ -178,8 +267,8 @@ The natively supported values for `target_formats` are:
- `md+html`:
- Generates the given template, parses it into a markdown document, and then generates HTML from it.
- Anything else, e.g. `txt`, `sql` or `py`
- Generates the given template as plaintext, and adds the given string as a file extension, e.g. `.txt`, `.sql` or
`.py`.
- Generates the given template as plaintext, and adds the given string as a file extension, e.g. `.txt`, `.sql` or
`.py`.

## Acknowledgements

Expand Down
42 changes: 30 additions & 12 deletions .metadock/templated_documents/repo_readme_template.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,23 +11,37 @@ Gitlab, or a static website. You can then compile your markdown documents using

A simple Metadock-enabled project might look something like this:

{{ codeblock(example_project.get("structure")) }}
{{ md.codeblock(example_project.get("structure")) }}

The root of your project is expected to have a `.metadock` folder, which can be generated from the CLI using
`metadock init`.

## Basic CLI Usage

The `metadock` CLI, installed using `pip install metadock`, has five basic commands, spelled out in the help message:
The `metadock` CLI, installed using `pip install metadock`, has {{ cli.get("commands") | length }} basic commands, spelled out in the help message:

{{ codeblock(cli.get("usage_string"), language="sh") }}
{{ md.codeblock(cli.get("usage_string"), language="sh") }}

Each of the commands supports a programmatic invocation from the `metadock.Metadock` class via a Python interface.

{% for command, spec in cli.get("commands").items() -%}
{%- set command_details -%}
- **Description**: {{ spec.get("description") }}
- **Usage**: {{ md.code(spec.get("usage")) }}
- **Python interface**:
{%- set python_interface = spec.get("python_interface") %}
- Name: {{ md.code(python_interface.get("method_name")) }}
- Signature: {{ md.code(python_interface.get("signature")) }}
{%- endset -%}
{{ html.details(html.summary(html.code("metadock " ~ command)), (command_details | md.convert)) }}
{% endfor %}

## Example Usage

In the example above, we can imagine the content of our template, `gitlab_mr_template.md`, to look something like this:

{{
codeblock(
md.codeblock(
example_project.get("templated_documents").get("gitlab_mr_template.md"),
language="md",
)
Expand All @@ -38,7 +52,7 @@ meet the same format and style requirements. An example *content schematic* whic
be in `gitlab_mr__feature1.yml`:

{{
codeblock(
md.codeblock(
example_project.get("content_schematics").get("gitlab_mr__feature1.yml"),
language="yml",
)
Expand All @@ -47,13 +61,13 @@ be in `gitlab_mr__feature1.yml`:
By invoking the CLI with `metadock build`, our template is compiled to look something like this, in a markdown file
called `generated_documents/gitlab_mr__feature1.md`:

{{ blockquote(example_project.get("generated_documents").get("gitlab_mr__feature1.md")) }}
{{ md.blockquote(example_project.get("generated_documents").get("gitlab_mr__feature1.md")) }}

Because the `target_formats` we chose included `md+html` _and_ `md`, we also get an HTML rendering of the document for free,
located at `generated_documents/gitlab_mr__feature_1.html`:

{{
codeblock(
md.codeblock(
example_project.get("generated_documents").get("gitlab_mr__feature1.html"),
language="html",
)
Expand All @@ -68,14 +82,18 @@ generated file.

The natively supported values for `target_formats` are:
{% for target_format, data in target_formats.items() %}
{{ list(code(target_format) ~ ":", list(data.get("description"))) }}
{{ md.list(md.code(target_format) ~ ":", md.list(data.get("description"))) }}
{% endfor -%}
- Anything else, e.g. `txt`, `sql` or `py`
- Generates the given template as plaintext, and adds the given string as a file extension, e.g. `.txt`, `.sql` or
`.py`.
{{
md.list(
"Anything else, e.g. `txt`, `sql` or `py`",
"Generates the given template as plaintext, and adds the given string as a file extension, e.g. `.txt`, `.sql` or
`.py`."
)
}}

## Acknowledgements

Author{% if (authors | length) > 1 %}s{% endif %}:

{{ list(*authors) }}
{{ md.list(*authors) }}
Loading

0 comments on commit a96ead0

Please sign in to comment.