# Godocs Jinja
**Godocs Jinja** is a **plugin** for the **Godocs CLI** that provides a **[Jinja2](https://jinja.palletsprojects.com/en/stable/) based constructor** implementation to generate documentation.
## 🤔 How to Use
To use this plugin you'll **need** to also have installed the **main godocs package**, which has the **core functionality** for the CLI.
Once **both packages are installed**, `godocs-jinja` will **automatically** be **detected** as a plugin and **registered** in the main **Godocs** program, thanks to its definition in the `project.entry-points."godocs.plugins"` table in the `pyproject.toml`.
## 📥 Installation
To start using this plugin with the **Godocs CLI**, you can **install** both the packages through **PIP**.
Here's the commands necessary to achieve that:
``` sh
# To install the main CLI:
pip install godocs
# To install this Jinja2 based constructor:
pip install godocs-jinja
```
> 💡 **HINT**: Depending on your needs, it may be useful to install packages in a **virtual environment**, as to not pollute your global env. Sometimes you may want to install stuff globally, though, it really depends.<br>
Generally speaking, I'd recommend **installing globally** if you're in a **CI/ CD runner**, for example, and installing in an **environment** if you're in your **local computer testing** out in a single repository.
If you desire to **isolate installation** in a `venv`, you should previously have run these **commands**:
``` sh
# To create a venv in a .venv folder:
python -m venv .venv
# To activate the created venv on Windows:
.venv/Scripts/activate
# Or, on Unix systems or Git Bash, for example:
source .venv/Scripts/activate
```
## 📚 Concepts
In this section you'll find some information about important concepts used in this project, which are nice to know to get a better understanding.
### 🗃️ Models
**Models** in this package are considered to be a certain **directory structures** that store **files used** in the doc **generation process** in a **predetermined way**.
By **default**, **one model** for `rst` documentation is defined, here's its structure as an example:
```
rst
├── templates
│ ├── index
│ │ └── index.jinja
│ └── class
│ │ ├── index.jinja
│ │ ├── heading.jinja
│ │ ├── description.jinja
│ │ ├── property_index.jinja
│ │ ├── method_index.jinja
│ │ ├── constant_descriptions.jinja
│ │ ├── enum_descriptions.jinja
│ │ ├── property_descriptions.jinja
│ │ ├── method_descriptions.jinja
│ │ └── signal_descriptions.jinja
└── filters.py
```
**Custom models** can be **passed** to the program by specifying a **directory** in the `-M` or `--models` **option** from the `jinja` constructor.
### 📐 Templates
**Templates** are **folders with** an `index.jinja` file **or** a `.jinja` **file** by itself, which defines a **Jinja template** used for **documentation generation**.
By **default**, there are **two templates** in the `rst` model: the **class template** and the **index template**. The **class template** defines how a **documentation page** about a **specific class** should be, and the **index template** specifies the output for an **index page** that allows **navigating between all classes with a toctree**.
**Custom templates** can be **passed** to the program by specifying a **directory** with templates in the `-T` or `--templates` **option** from the `jinja` constructor.
### 🔨 Filters
**Filters** are **functions** that **return** `strings` which can be **used by** the **Jinja construction** process, thanks to the `JinjaConstructor` defining them as [Jinja filters](https://jinja.palletsprojects.com/en/stable/api/#custom-filters).
Filters can be **passed** to the **CLI** by **pointing to a file** with the given functions via the `-F` **or** `--filters` **option** in the `jinja` constructor.
By **default**, the `rst` **model** comes with a few **filters**, which **stay** in the `filter.py` are used throughout the **built-in templates**.
### 🏗️ Builders
**Builders** are also **functions**, but these determine how the **construction should respond to specific templates**. This is done internally by **mapping each builder to a template name**.
As an **example**, there are default builders for the **class** and **index** templates. The **class builder** generates output **files for each class** in the documentation, different from the **index builder**, which only generates **one index file** output.
**For each template** that should be used, there should be an **equivalent builder**, so `godocs-jinja` knows how to generate its output specifically. That's why by **default** there are the `class` and `index` **builders** - because there are the `class` and `index` **templates**.
For passing **custom builders**, you can use the `-B` or `--builders` option in the `jinja` constructor pointing to a **script with functions** representing the **builders**. The **names of the functions** should **match** the **name of the templates** they should build.
## 🎛️ Commands
This **plugin adds** the `jinja` constructor as a **subcommand** to the main CLI's `construct` command. This subcommand can then be used to effectively **generate docs** using **Jinja2**.
Down below are some quick **examples** of how the commands, arguments and options added by `godocs-jinja` to **generate documentation** can be used (if you installed in a **virtual environment**, make sure to have it **activated** before effectively using the program).
If you want a more **in depth overview** of the features available, you can always use the `-h` / `--help` option with **any command**.
``` sh
# Generates documentation based on the XML in the input-dir inside the output-dir, in the RST language, by default.
godocs construct jinja <input-dir> <output-dir>
# Generates documentation based on the XML from the input-dir inside the output-dir, in the RST language, by default, translating the syntax of any text within it using the custom translator in the translator-path.
godocs construct jinja --translator <translator-path> <input-dir> <output-dir>
# Generates documentation based on the XML from the input-dir inside the output-dir, using the model specified by md-model, with the md file suffix, translating the syntax of any text within the XML using the custom translator in the md-translator path.
godocs construct jinja --translator <md-translator> --format md --model <md-model> <input-dir> <output-dir>
```
## 📝 Custom Options
The documentation process often needs some **data that can't be obtained** directly from the **XML class reference** generated by **Godot**. That's why more **properties can be passed** via a special `godocs-options.json` file.
You can write **any data** your documentation will potentially need **inside this file** and **specify its path** through the `--options-file` option in the `jinja` command. **Godocs** `construct` logic will then **parse its data** and make it **available in the building context inside an options property**.
If you use the **default** `rst` **templates**, here's the **options** that you'll want to specify:
- `name`: The title of the documentation in the index file
- `description`: The description for the documentation in the index file
- `toc_depth`: The depth of the main `toctree` of the documentation in the index file
## 🧑💻 Developing
For **development isolation**, it is recommended to be inside a **virtual environment**, which can be accomplished by following the **steps** described at the end of the **Installation section**, quickly recaping:
``` sh
python -m venv .venv
# On Windows:
.venv/Scripts/activate
# Or, on Unix:
source .venv/Scripts/activate
```
Now, the project comes with a `pyproject.toml`, which specifies its **dependencies** depending on the **environment**.
The **main dependency** of this package is the `jinja2` tool. Besides that, this project has some **dev dependencies**, to allow **building and testing**. Finally, `godocs` is considered a **peer dependency** here, to allow users to use the version they want, based on their environment.
If you want to **install** the dependencies, you can use the following **commands**:
``` sh
# For production only dependencies:
pip install .
# For development dependencies:
pip install .[dev]
# For peer dependencies:
pip install .[peer]
```
If you're going to **develop**, though, I'd recommend you to rather **install the project itself** in **editable mode**, which would allow you to **make changes** and **test them** out in **real time**, **without having to rebuild and reinstall**. Here's the command to achieve that:
``` sh
pip install --editable .
```
## 🧪 Testing
This project uses `pytest` as its **test framework**, which means in order to **execute tests**, you should use the **following command**:
``` sh
pytest
```
The **test files** are located under the `tests` directory, distributed under a **structure** that **mirrors the source code** arrangement.
## 📦 Building
To **build this project** for production, the `build` **dependency is needed**, which is specified in the **dev dependencies** from `pyproject.toml`.
With that **dependency installed** (through the **installation of the dev dependencies**, or its manual installation), the following command can be used:
``` sh
python -m build .
```
This will use the `setuptools` **build backend** in an **isolated temporary environment** to **create the distributables**.
When executed, **there should be** a `dist` folder with a `.tar.gz` archive and a `.whl` build.
## 🚀 Deploying
To deploy this package, the following command can be used:
``` sh
python -m twine upload dist/*
```
Raw data
{
"_id": null,
"home_page": null,
"name": "godocs-jinja",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": null,
"keywords": "python, godot, documentation, docs, godocs, sphinx, jinja2",
"author": null,
"author_email": "\"Daniel Sousa (nadjiel)\" <oliveira.daaaaniel@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ee/22/55580b203ec616b766bfffa5a0921ae38c0ec35fc936e4a26eb433329051/godocs_jinja-0.1.2.tar.gz",
"platform": null,
"description": "# Godocs Jinja\r\n\r\n**Godocs Jinja** is a **plugin** for the **Godocs CLI** that provides a **[Jinja2](https://jinja.palletsprojects.com/en/stable/) based constructor** implementation to generate documentation.\r\n\r\n## \ud83e\udd14 How to Use\r\n\r\nTo use this plugin you'll **need** to also have installed the **main godocs package**, which has the **core functionality** for the CLI.\r\n\r\nOnce **both packages are installed**, `godocs-jinja` will **automatically** be **detected** as a plugin and **registered** in the main **Godocs** program, thanks to its definition in the `project.entry-points.\"godocs.plugins\"` table in the `pyproject.toml`.\r\n\r\n## \ud83d\udce5 Installation\r\n\r\nTo start using this plugin with the **Godocs CLI**, you can **install** both the packages through **PIP**.\r\n\r\nHere's the commands necessary to achieve that:\r\n\r\n``` sh\r\n# To install the main CLI:\r\npip install godocs\r\n\r\n# To install this Jinja2 based constructor:\r\npip install godocs-jinja\r\n```\r\n\r\n> \ud83d\udca1 **HINT**: Depending on your needs, it may be useful to install packages in a **virtual environment**, as to not pollute your global env. Sometimes you may want to install stuff globally, though, it really depends.<br>\r\nGenerally speaking, I'd recommend **installing globally** if you're in a **CI/ CD runner**, for example, and installing in an **environment** if you're in your **local computer testing** out in a single repository.\r\n\r\nIf you desire to **isolate installation** in a `venv`, you should previously have run these **commands**:\r\n\r\n``` sh\r\n# To create a venv in a .venv folder:\r\npython -m venv .venv\r\n\r\n# To activate the created venv on Windows:\r\n.venv/Scripts/activate\r\n# Or, on Unix systems or Git Bash, for example:\r\nsource .venv/Scripts/activate\r\n```\r\n\r\n## \ud83d\udcda Concepts\r\n\r\nIn this section you'll find some information about important concepts used in this project, which are nice to know to get a better understanding.\r\n\r\n### \ud83d\uddc3\ufe0f Models\r\n\r\n**Models** in this package are considered to be a certain **directory structures** that store **files used** in the doc **generation process** in a **predetermined way**.\r\n\r\nBy **default**, **one model** for `rst` documentation is defined, here's its structure as an example:\r\n\r\n```\r\nrst\r\n\u251c\u2500\u2500 templates\r\n\u2502 \u251c\u2500\u2500 index\r\n\u2502 \u2502 \u2514\u2500\u2500 index.jinja\r\n\u2502 \u2514\u2500\u2500 class \r\n\u2502 \u2502 \u251c\u2500\u2500 index.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 heading.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 description.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 property_index.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 method_index.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 constant_descriptions.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 enum_descriptions.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 property_descriptions.jinja\r\n\u2502 \u2502 \u251c\u2500\u2500 method_descriptions.jinja\r\n\u2502 \u2502 \u2514\u2500\u2500 signal_descriptions.jinja\r\n\u2514\u2500\u2500 filters.py \r\n```\r\n\r\n**Custom models** can be **passed** to the program by specifying a **directory** in the `-M` or `--models` **option** from the `jinja` constructor.\r\n\r\n### \ud83d\udcd0 Templates\r\n\r\n**Templates** are **folders with** an `index.jinja` file **or** a `.jinja` **file** by itself, which defines a **Jinja template** used for **documentation generation**.\r\n\r\nBy **default**, there are **two templates** in the `rst` model: the **class template** and the **index template**. The **class template** defines how a **documentation page** about a **specific class** should be, and the **index template** specifies the output for an **index page** that allows **navigating between all classes with a toctree**. \r\n\r\n**Custom templates** can be **passed** to the program by specifying a **directory** with templates in the `-T` or `--templates` **option** from the `jinja` constructor.\r\n\r\n### \ud83d\udd28 Filters\r\n\r\n**Filters** are **functions** that **return** `strings` which can be **used by** the **Jinja construction** process, thanks to the `JinjaConstructor` defining them as [Jinja filters](https://jinja.palletsprojects.com/en/stable/api/#custom-filters).\r\n\r\nFilters can be **passed** to the **CLI** by **pointing to a file** with the given functions via the `-F` **or** `--filters` **option** in the `jinja` constructor.\r\n\r\nBy **default**, the `rst` **model** comes with a few **filters**, which **stay** in the `filter.py` are used throughout the **built-in templates**.\r\n\r\n### \ud83c\udfd7\ufe0f Builders\r\n\r\n**Builders** are also **functions**, but these determine how the **construction should respond to specific templates**. This is done internally by **mapping each builder to a template name**.\r\n\r\nAs an **example**, there are default builders for the **class** and **index** templates. The **class builder** generates output **files for each class** in the documentation, different from the **index builder**, which only generates **one index file** output.\r\n\r\n**For each template** that should be used, there should be an **equivalent builder**, so `godocs-jinja` knows how to generate its output specifically. That's why by **default** there are the `class` and `index` **builders** - because there are the `class` and `index` **templates**.\r\n\r\nFor passing **custom builders**, you can use the `-B` or `--builders` option in the `jinja` constructor pointing to a **script with functions** representing the **builders**. The **names of the functions** should **match** the **name of the templates** they should build.\r\n\r\n## \ud83c\udf9b\ufe0f Commands\r\n\r\nThis **plugin adds** the `jinja` constructor as a **subcommand** to the main CLI's `construct` command. This subcommand can then be used to effectively **generate docs** using **Jinja2**.\r\n\r\nDown below are some quick **examples** of how the commands, arguments and options added by `godocs-jinja` to **generate documentation** can be used (if you installed in a **virtual environment**, make sure to have it **activated** before effectively using the program).\r\n\r\nIf you want a more **in depth overview** of the features available, you can always use the `-h` / `--help` option with **any command**.\r\n\r\n``` sh\r\n# Generates documentation based on the XML in the input-dir inside the output-dir, in the RST language, by default.\r\ngodocs construct jinja <input-dir> <output-dir>\r\n\r\n# Generates documentation based on the XML from the input-dir inside the output-dir, in the RST language, by default, translating the syntax of any text within it using the custom translator in the translator-path.\r\ngodocs construct jinja --translator <translator-path> <input-dir> <output-dir>\r\n\r\n# Generates documentation based on the XML from the input-dir inside the output-dir, using the model specified by md-model, with the md file suffix, translating the syntax of any text within the XML using the custom translator in the md-translator path.\r\ngodocs construct jinja --translator <md-translator> --format md --model <md-model> <input-dir> <output-dir>\r\n```\r\n\r\n## \ud83d\udcdd Custom Options\r\n\r\nThe documentation process often needs some **data that can't be obtained** directly from the **XML class reference** generated by **Godot**. That's why more **properties can be passed** via a special `godocs-options.json` file.\r\n\r\nYou can write **any data** your documentation will potentially need **inside this file** and **specify its path** through the `--options-file` option in the `jinja` command. **Godocs** `construct` logic will then **parse its data** and make it **available in the building context inside an options property**.\r\n\r\nIf you use the **default** `rst` **templates**, here's the **options** that you'll want to specify:\r\n\r\n- `name`: The title of the documentation in the index file\r\n- `description`: The description for the documentation in the index file\r\n- `toc_depth`: The depth of the main `toctree` of the documentation in the index file\r\n\r\n## \ud83e\uddd1\u200d\ud83d\udcbb Developing\r\n\r\nFor **development isolation**, it is recommended to be inside a **virtual environment**, which can be accomplished by following the **steps** described at the end of the **Installation section**, quickly recaping:\r\n\r\n``` sh\r\npython -m venv .venv\r\n\r\n# On Windows:\r\n.venv/Scripts/activate\r\n# Or, on Unix:\r\nsource .venv/Scripts/activate\r\n```\r\n\r\nNow, the project comes with a `pyproject.toml`, which specifies its **dependencies** depending on the **environment**.\r\n\r\nThe **main dependency** of this package is the `jinja2` tool. Besides that, this project has some **dev dependencies**, to allow **building and testing**. Finally, `godocs` is considered a **peer dependency** here, to allow users to use the version they want, based on their environment.\r\n\r\nIf you want to **install** the dependencies, you can use the following **commands**:\r\n\r\n``` sh\r\n# For production only dependencies:\r\npip install .\r\n\r\n# For development dependencies:\r\npip install .[dev]\r\n\r\n# For peer dependencies:\r\npip install .[peer]\r\n```\r\n\r\nIf you're going to **develop**, though, I'd recommend you to rather **install the project itself** in **editable mode**, which would allow you to **make changes** and **test them** out in **real time**, **without having to rebuild and reinstall**. Here's the command to achieve that:\r\n\r\n``` sh\r\npip install --editable .\r\n```\r\n\r\n## \ud83e\uddea Testing\r\n\r\nThis project uses `pytest` as its **test framework**, which means in order to **execute tests**, you should use the **following command**:\r\n\r\n``` sh\r\npytest\r\n```\r\n\r\nThe **test files** are located under the `tests` directory, distributed under a **structure** that **mirrors the source code** arrangement.\r\n\r\n## \ud83d\udce6 Building\r\n\r\nTo **build this project** for production, the `build` **dependency is needed**, which is specified in the **dev dependencies** from `pyproject.toml`.\r\n\r\nWith that **dependency installed** (through the **installation of the dev dependencies**, or its manual installation), the following command can be used:\r\n\r\n``` sh\r\npython -m build .\r\n```\r\n\r\nThis will use the `setuptools` **build backend** in an **isolated temporary environment** to **create the distributables**.\r\n\r\nWhen executed, **there should be** a `dist` folder with a `.tar.gz` archive and a `.whl` build.\r\n\r\n## \ud83d\ude80 Deploying\r\n\r\nTo deploy this package, the following command can be used:\r\n\r\n``` sh\r\npython -m twine upload dist/*\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Jinja implementation of constructor for Godocs CLI",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/godocs-godot/godocs-jinja",
"Issues": "https://github.com/godocs-godot/godocs-jinja/issues"
},
"split_keywords": [
"python",
" godot",
" documentation",
" docs",
" godocs",
" sphinx",
" jinja2"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0fc695a8896c668e890e6bc2ab5768f3b6c87275ab4e283511fc4c60ef91c3be",
"md5": "2add4543180907e8463d688386578691",
"sha256": "dfc90376aca1f3f990d2451b3f6099271da06bc04df66500cdb1e91bf167c10b"
},
"downloads": -1,
"filename": "godocs_jinja-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2add4543180907e8463d688386578691",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 18834,
"upload_time": "2025-10-22T01:18:21",
"upload_time_iso_8601": "2025-10-22T01:18:21.317841Z",
"url": "https://files.pythonhosted.org/packages/0f/c6/95a8896c668e890e6bc2ab5768f3b6c87275ab4e283511fc4c60ef91c3be/godocs_jinja-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ee2255580b203ec616b766bfffa5a0921ae38c0ec35fc936e4a26eb433329051",
"md5": "81411529e6372ac6c1845a84b57f442b",
"sha256": "5f7dd809d968473c54ab70ac65870ddc2f646fb597c3efe75d5d04215352885c"
},
"downloads": -1,
"filename": "godocs_jinja-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "81411529e6372ac6c1845a84b57f442b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 17672,
"upload_time": "2025-10-22T01:18:22",
"upload_time_iso_8601": "2025-10-22T01:18:22.695912Z",
"url": "https://files.pythonhosted.org/packages/ee/22/55580b203ec616b766bfffa5a0921ae38c0ec35fc936e4a26eb433329051/godocs_jinja-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 01:18:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "godocs-godot",
"github_project": "godocs-jinja",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "godocs-jinja"
}
JSON
