diff options
| author | CoprDistGit <infra@openeuler.org> | 2023-04-11 04:24:03 +0000 |
|---|---|---|
| committer | CoprDistGit <infra@openeuler.org> | 2023-04-11 04:24:03 +0000 |
| commit | 6216b775a3c6959120b06fadab42628e0f9f92d8 (patch) | |
| tree | 8cbb35496b5977d95908d997cd9bda3fd947b2ee | |
| parent | a4e70479de615b82be68724d17d2879527955d82 (diff) | |
automatic import of python-mkdocs-macros-plugin
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-mkdocs-macros-plugin.spec | 716 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 718 insertions, 0 deletions
@@ -0,0 +1 @@ +/mkdocs-macros-plugin-0.7.0.tar.gz diff --git a/python-mkdocs-macros-plugin.spec b/python-mkdocs-macros-plugin.spec new file mode 100644 index 0000000..5a1d24a --- /dev/null +++ b/python-mkdocs-macros-plugin.spec @@ -0,0 +1,716 @@ +%global _empty_manifest_terminate_build 0 +Name: python-mkdocs-macros-plugin +Version: 0.7.0 +Release: 1 +Summary: Unleash the power of MkDocs with macros and variables +License: MIT +URL: https://github.com/fralau/mkdocs_macros_plugin +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/1b/43/c199e0bdb4c56bb392c3559e9023122b0be2d457763c48b9774f5fca500d/mkdocs-macros-plugin-0.7.0.tar.gz +BuildArch: noarch + +Requires: python3-mkdocs +Requires: python3-jinja2 +Requires: python3-termcolor +Requires: python3-pyyaml +Requires: python3-dateutil +Requires: python3-mkdocs-macros-test +Requires: python3-mkdocs-material +Requires: python3-mkdocs-include-markdown-plugin + +%description +# mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros + + +[](https://opensource.org/licenses/MIT) + + + + + +* **View the [mkdocs-macro documentation](https://mkdocs-macros-plugin.readthedocs.io/) on Read the Docs** +* View the [general Mkdocs documentation](https://www.mkdocs.org/) + +<!-- To update, run the following command: +markdown-toc -i README.md +--> + +<!-- toc --> + +- [mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros](#mkdocs-macros-plugin-unleash-the-power-of-mkdocs-with-variables-and-macros) + - [Overview](#Overview) + - [Using variables](#Using-variables) + - [Defining variables](#Defining-variables) + - [Macros and filters](#Macros-and-filters) + - [Installation](#Installation) + - [Prerequisites](#Prerequisites) + - [Standard installation](#Standard-installation) + - ["Manual installation"](#"Manual-installation") + - [Development/test installation](#Development/test-installation) + - [Declaration of plugin](#Declaration-of-plugin) + - [Check that it works](#Check-that-it-works) + - [Using pluglets](#Using-pluglets) + - [What are pluglets?](#What-are-pluglets?) + - [How to add a pluglet to an mkdocs project?](#How-to-add-a-pluglet-to-an-mkdocs-project?) + - [How to write a pluglet?](#How-to-write-a-pluglet?) + +<!-- tocstop --> + +## Overview +**mkdocs-macros-plugin** is a plugin that makes it easier for contributors +of an [MkDocs](https://www.mkdocs.org/) website to produce richer and more beautiful pages. It transforms the markdown pages +into [jinja2](https://jinja.palletsprojects.com/en/2.10.x/) templates +that use **variables**, calls to **macros** and custom **filters**. + +> **You can also partially replace MkDocs plugins with mkdocs-macros modules, +> and [pluglets](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/) +> (pre-installed modules).** + + +### Using variables +You can leverage the power of Python in markdown thanks to jinja2 +by writing this : + +```markdown +The unit price of product A is {{ unit_price }} EUR. +Taking the standard discount into account, +the sale price of 50 units is {{ price(unit_price, 50) }} EUR. +``` + +If you defined a `price()` function, this could translate into: + +``` +The unit price of product A is 10.00 EUR. +Taking the standard discount into account, +the sale price of 50 units is 450.00 EUR. +``` + +> The result of a macro can be **HTML code**: +this makes macros especially useful +to make custom extensions to the syntax of markdown, such as buttons, +calls to email, embedding YouTube videos, etc. + +It is possible to use the wide range of facilities provided by +[Jinja2 templates](http://jinja.pocoo.org/docs/2.10/templates/) such +as conditions (`{% if ... %}`) and loops (`{% for ... %}`). + +### Defining variables + +Regular **variables** can be defined in five ways: + +| No | Validity | For whom | Description | +| --- | --- | --- | ---- | +| 1. | global | designer of the website | in the `mkdocs.yml` file, under the `extra` heading | +| 2. | global | contributor | in external yaml definition files | +| 3. | global | programmer | in a `main.py` file (Python), by adding them to a dictionary | +| 4. | local (page) | writer | in the YAML header of each Markdown page | +| 5. | local (page) | writer | with a `{%set variable = value %}` statement | + +In addition, predefined objects are provided (local and global), typically +for the environment, project, page, git information, etc. + + +### Macros and filters +Similarly programmers can define their own **macros** and **filters**, +as Python functions in the `main.py` file, +which the users will then be able to +use without much difficulty, as jinja2 directives in the markdown page. + + + +## Installation + +### Prerequisites + + - Python version > 3.5 + - MkDocs version >= 1.0 (it should work > 0.17 + (it should be compatible with post 1.0 versions) + +### Standard installation +``` +pip install mkdocs-macros-plugin +``` + +### "Manual installation" +To install the package, download it and run: + +``` +pip install . +# or... +python setup.py install +``` + +### Development/test installation +To install the extra dependencies required for testing the package, run: + +``` +pip install "mkdocs-macros-plugin[test]" +``` + +### Declaration of plugin +Declare the plugin in the the file `mkdocs.yml`: + +```yaml +plugins: + - search + - macros +``` + +> **Note:** If you have no `plugins` entry in your config file yet, +you should also add the `search` plugin. +If no `plugins` entry is set, MkDocs enables `search` by default; but +if you use it, then you have to declare it explicitly. + +### Check that it works +The recommended way to check that the plugin works properly is to add the +following command in one of the pages of your site (let's say `info.md`): + +``` +{{ macros_info() }} +``` + +In the terminal, restart the environment: + +``` +> mkdocs serve +```` +You will notice that additional information now appears in the terminal: + +``` +INFO - Building documentation... +[macros] Macros arguments: {'module_name': 'main', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': ''} +``` + +Within the browser (e.g. http://127.0.0.1:8000/info), you should +see a description of the plugins environment: + + + +If you see it that information, you should be all set. + +Give a good look at the General List, since it gives you an overview +of what you can do out of the box with the macros plugin. + +The other parts give you more detailed information. + + +## Using pluglets + +### What are pluglets? + +**Pluglets** are small, easy-to-write programs +that use mkdocs-macro's foundation +to offer services to mkdocs projects, which would normally +be offered by plugins. + +Pluglets are Python packages, which can be hosted on github, and +distributed through [PyPI](https://pypi.org/). + + +### How to add a pluglet to an mkdocs project? + +Install it: + +```python +pip install <pluglet_name> +``` + +Declare it in the project's config (`mkdocs.yml`) file: + +```yaml +plugins: + - search + - macros: + modules: + - <pluglet_name> +``` + +### How to write a pluglet? + +[See instructions in the documentation](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/). + +A sample pluglet can be found in [mkdocs-test (github)](https://github.com/fralau/mkdocs-macros-test). + + + +%package -n python3-mkdocs-macros-plugin +Summary: Unleash the power of MkDocs with macros and variables +Provides: python-mkdocs-macros-plugin +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-mkdocs-macros-plugin +# mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros + + +[](https://opensource.org/licenses/MIT) + + + + + +* **View the [mkdocs-macro documentation](https://mkdocs-macros-plugin.readthedocs.io/) on Read the Docs** +* View the [general Mkdocs documentation](https://www.mkdocs.org/) + +<!-- To update, run the following command: +markdown-toc -i README.md +--> + +<!-- toc --> + +- [mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros](#mkdocs-macros-plugin-unleash-the-power-of-mkdocs-with-variables-and-macros) + - [Overview](#Overview) + - [Using variables](#Using-variables) + - [Defining variables](#Defining-variables) + - [Macros and filters](#Macros-and-filters) + - [Installation](#Installation) + - [Prerequisites](#Prerequisites) + - [Standard installation](#Standard-installation) + - ["Manual installation"](#"Manual-installation") + - [Development/test installation](#Development/test-installation) + - [Declaration of plugin](#Declaration-of-plugin) + - [Check that it works](#Check-that-it-works) + - [Using pluglets](#Using-pluglets) + - [What are pluglets?](#What-are-pluglets?) + - [How to add a pluglet to an mkdocs project?](#How-to-add-a-pluglet-to-an-mkdocs-project?) + - [How to write a pluglet?](#How-to-write-a-pluglet?) + +<!-- tocstop --> + +## Overview +**mkdocs-macros-plugin** is a plugin that makes it easier for contributors +of an [MkDocs](https://www.mkdocs.org/) website to produce richer and more beautiful pages. It transforms the markdown pages +into [jinja2](https://jinja.palletsprojects.com/en/2.10.x/) templates +that use **variables**, calls to **macros** and custom **filters**. + +> **You can also partially replace MkDocs plugins with mkdocs-macros modules, +> and [pluglets](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/) +> (pre-installed modules).** + + +### Using variables +You can leverage the power of Python in markdown thanks to jinja2 +by writing this : + +```markdown +The unit price of product A is {{ unit_price }} EUR. +Taking the standard discount into account, +the sale price of 50 units is {{ price(unit_price, 50) }} EUR. +``` + +If you defined a `price()` function, this could translate into: + +``` +The unit price of product A is 10.00 EUR. +Taking the standard discount into account, +the sale price of 50 units is 450.00 EUR. +``` + +> The result of a macro can be **HTML code**: +this makes macros especially useful +to make custom extensions to the syntax of markdown, such as buttons, +calls to email, embedding YouTube videos, etc. + +It is possible to use the wide range of facilities provided by +[Jinja2 templates](http://jinja.pocoo.org/docs/2.10/templates/) such +as conditions (`{% if ... %}`) and loops (`{% for ... %}`). + +### Defining variables + +Regular **variables** can be defined in five ways: + +| No | Validity | For whom | Description | +| --- | --- | --- | ---- | +| 1. | global | designer of the website | in the `mkdocs.yml` file, under the `extra` heading | +| 2. | global | contributor | in external yaml definition files | +| 3. | global | programmer | in a `main.py` file (Python), by adding them to a dictionary | +| 4. | local (page) | writer | in the YAML header of each Markdown page | +| 5. | local (page) | writer | with a `{%set variable = value %}` statement | + +In addition, predefined objects are provided (local and global), typically +for the environment, project, page, git information, etc. + + +### Macros and filters +Similarly programmers can define their own **macros** and **filters**, +as Python functions in the `main.py` file, +which the users will then be able to +use without much difficulty, as jinja2 directives in the markdown page. + + + +## Installation + +### Prerequisites + + - Python version > 3.5 + - MkDocs version >= 1.0 (it should work > 0.17 + (it should be compatible with post 1.0 versions) + +### Standard installation +``` +pip install mkdocs-macros-plugin +``` + +### "Manual installation" +To install the package, download it and run: + +``` +pip install . +# or... +python setup.py install +``` + +### Development/test installation +To install the extra dependencies required for testing the package, run: + +``` +pip install "mkdocs-macros-plugin[test]" +``` + +### Declaration of plugin +Declare the plugin in the the file `mkdocs.yml`: + +```yaml +plugins: + - search + - macros +``` + +> **Note:** If you have no `plugins` entry in your config file yet, +you should also add the `search` plugin. +If no `plugins` entry is set, MkDocs enables `search` by default; but +if you use it, then you have to declare it explicitly. + +### Check that it works +The recommended way to check that the plugin works properly is to add the +following command in one of the pages of your site (let's say `info.md`): + +``` +{{ macros_info() }} +``` + +In the terminal, restart the environment: + +``` +> mkdocs serve +```` +You will notice that additional information now appears in the terminal: + +``` +INFO - Building documentation... +[macros] Macros arguments: {'module_name': 'main', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': ''} +``` + +Within the browser (e.g. http://127.0.0.1:8000/info), you should +see a description of the plugins environment: + + + +If you see it that information, you should be all set. + +Give a good look at the General List, since it gives you an overview +of what you can do out of the box with the macros plugin. + +The other parts give you more detailed information. + + +## Using pluglets + +### What are pluglets? + +**Pluglets** are small, easy-to-write programs +that use mkdocs-macro's foundation +to offer services to mkdocs projects, which would normally +be offered by plugins. + +Pluglets are Python packages, which can be hosted on github, and +distributed through [PyPI](https://pypi.org/). + + +### How to add a pluglet to an mkdocs project? + +Install it: + +```python +pip install <pluglet_name> +``` + +Declare it in the project's config (`mkdocs.yml`) file: + +```yaml +plugins: + - search + - macros: + modules: + - <pluglet_name> +``` + +### How to write a pluglet? + +[See instructions in the documentation](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/). + +A sample pluglet can be found in [mkdocs-test (github)](https://github.com/fralau/mkdocs-macros-test). + + + +%package help +Summary: Development documents and examples for mkdocs-macros-plugin +Provides: python3-mkdocs-macros-plugin-doc +%description help +# mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros + + +[](https://opensource.org/licenses/MIT) + + + + + +* **View the [mkdocs-macro documentation](https://mkdocs-macros-plugin.readthedocs.io/) on Read the Docs** +* View the [general Mkdocs documentation](https://www.mkdocs.org/) + +<!-- To update, run the following command: +markdown-toc -i README.md +--> + +<!-- toc --> + +- [mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros](#mkdocs-macros-plugin-unleash-the-power-of-mkdocs-with-variables-and-macros) + - [Overview](#Overview) + - [Using variables](#Using-variables) + - [Defining variables](#Defining-variables) + - [Macros and filters](#Macros-and-filters) + - [Installation](#Installation) + - [Prerequisites](#Prerequisites) + - [Standard installation](#Standard-installation) + - ["Manual installation"](#"Manual-installation") + - [Development/test installation](#Development/test-installation) + - [Declaration of plugin](#Declaration-of-plugin) + - [Check that it works](#Check-that-it-works) + - [Using pluglets](#Using-pluglets) + - [What are pluglets?](#What-are-pluglets?) + - [How to add a pluglet to an mkdocs project?](#How-to-add-a-pluglet-to-an-mkdocs-project?) + - [How to write a pluglet?](#How-to-write-a-pluglet?) + +<!-- tocstop --> + +## Overview +**mkdocs-macros-plugin** is a plugin that makes it easier for contributors +of an [MkDocs](https://www.mkdocs.org/) website to produce richer and more beautiful pages. It transforms the markdown pages +into [jinja2](https://jinja.palletsprojects.com/en/2.10.x/) templates +that use **variables**, calls to **macros** and custom **filters**. + +> **You can also partially replace MkDocs plugins with mkdocs-macros modules, +> and [pluglets](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/) +> (pre-installed modules).** + + +### Using variables +You can leverage the power of Python in markdown thanks to jinja2 +by writing this : + +```markdown +The unit price of product A is {{ unit_price }} EUR. +Taking the standard discount into account, +the sale price of 50 units is {{ price(unit_price, 50) }} EUR. +``` + +If you defined a `price()` function, this could translate into: + +``` +The unit price of product A is 10.00 EUR. +Taking the standard discount into account, +the sale price of 50 units is 450.00 EUR. +``` + +> The result of a macro can be **HTML code**: +this makes macros especially useful +to make custom extensions to the syntax of markdown, such as buttons, +calls to email, embedding YouTube videos, etc. + +It is possible to use the wide range of facilities provided by +[Jinja2 templates](http://jinja.pocoo.org/docs/2.10/templates/) such +as conditions (`{% if ... %}`) and loops (`{% for ... %}`). + +### Defining variables + +Regular **variables** can be defined in five ways: + +| No | Validity | For whom | Description | +| --- | --- | --- | ---- | +| 1. | global | designer of the website | in the `mkdocs.yml` file, under the `extra` heading | +| 2. | global | contributor | in external yaml definition files | +| 3. | global | programmer | in a `main.py` file (Python), by adding them to a dictionary | +| 4. | local (page) | writer | in the YAML header of each Markdown page | +| 5. | local (page) | writer | with a `{%set variable = value %}` statement | + +In addition, predefined objects are provided (local and global), typically +for the environment, project, page, git information, etc. + + +### Macros and filters +Similarly programmers can define their own **macros** and **filters**, +as Python functions in the `main.py` file, +which the users will then be able to +use without much difficulty, as jinja2 directives in the markdown page. + + + +## Installation + +### Prerequisites + + - Python version > 3.5 + - MkDocs version >= 1.0 (it should work > 0.17 + (it should be compatible with post 1.0 versions) + +### Standard installation +``` +pip install mkdocs-macros-plugin +``` + +### "Manual installation" +To install the package, download it and run: + +``` +pip install . +# or... +python setup.py install +``` + +### Development/test installation +To install the extra dependencies required for testing the package, run: + +``` +pip install "mkdocs-macros-plugin[test]" +``` + +### Declaration of plugin +Declare the plugin in the the file `mkdocs.yml`: + +```yaml +plugins: + - search + - macros +``` + +> **Note:** If you have no `plugins` entry in your config file yet, +you should also add the `search` plugin. +If no `plugins` entry is set, MkDocs enables `search` by default; but +if you use it, then you have to declare it explicitly. + +### Check that it works +The recommended way to check that the plugin works properly is to add the +following command in one of the pages of your site (let's say `info.md`): + +``` +{{ macros_info() }} +``` + +In the terminal, restart the environment: + +``` +> mkdocs serve +```` +You will notice that additional information now appears in the terminal: + +``` +INFO - Building documentation... +[macros] Macros arguments: {'module_name': 'main', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': ''} +``` + +Within the browser (e.g. http://127.0.0.1:8000/info), you should +see a description of the plugins environment: + + + +If you see it that information, you should be all set. + +Give a good look at the General List, since it gives you an overview +of what you can do out of the box with the macros plugin. + +The other parts give you more detailed information. + + +## Using pluglets + +### What are pluglets? + +**Pluglets** are small, easy-to-write programs +that use mkdocs-macro's foundation +to offer services to mkdocs projects, which would normally +be offered by plugins. + +Pluglets are Python packages, which can be hosted on github, and +distributed through [PyPI](https://pypi.org/). + + +### How to add a pluglet to an mkdocs project? + +Install it: + +```python +pip install <pluglet_name> +``` + +Declare it in the project's config (`mkdocs.yml`) file: + +```yaml +plugins: + - search + - macros: + modules: + - <pluglet_name> +``` + +### How to write a pluglet? + +[See instructions in the documentation](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/). + +A sample pluglet can be found in [mkdocs-test (github)](https://github.com/fralau/mkdocs-macros-test). + + + +%prep +%autosetup -n mkdocs-macros-plugin-0.7.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-mkdocs-macros-plugin -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Tue Apr 11 2023 Python_Bot <Python_Bot@openeuler.org> - 0.7.0-1 +- Package Spec generated @@ -0,0 +1 @@ +a2fe624b3ca5a54894d05d3aac64fc02 mkdocs-macros-plugin-0.7.0.tar.gz |