diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-mkdocs-codeinclude-plugin.spec | 533 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 535 insertions, 0 deletions
@@ -0,0 +1 @@ +/mkdocs-codeinclude-plugin-0.2.1.tar.gz diff --git a/python-mkdocs-codeinclude-plugin.spec b/python-mkdocs-codeinclude-plugin.spec new file mode 100644 index 0000000..65cb8cc --- /dev/null +++ b/python-mkdocs-codeinclude-plugin.spec @@ -0,0 +1,533 @@ +%global _empty_manifest_terminate_build 0 +Name: python-mkdocs-codeinclude-plugin +Version: 0.2.1 +Release: 1 +Summary: A plugin to include code snippets into mkdocs pages +License: MIT +URL: https://github.com/rnorth/mkdocs-codeinclude-plugin +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/1b/b5/f72df157abc7f85e33ffa417464e9dd535ef5fda7654eda41190047a53b6/mkdocs-codeinclude-plugin-0.2.1.tar.gz +BuildArch: noarch + +Requires: python3-mkdocs +Requires: python3-pygments + +%description +# mkdocs-codeinclude-plugin + +A plugin for mkdocs that allows some advanced 'includes' functionality to be used for embedded code blocks. +This is effectively an extended Markdown format, but is intended to degrade gracefully when rendered with a different renderer. + +## Installation + +1. Install the plugin: + + ``` + pip install mkdocs-codeinclude-plugin + ``` + +2. Add `codeinclude` to the list of your MkDocs plugins (typically listed in `mkdocs.yml`): + + ```yaml + plugins: + - codeinclude + ``` + +3. The plugin should be configured use an appropriate form of tabbed fences, depending on the version of +[`pymdown-extensions`](https://github.com/facelessuser/pymdown-extensions) that is installed. +Tabbed fences provide a 'title' for code blocks, and adjacent code blocks will appear as a multi-tabbed code block. + + a. For version 8.x of `pymdown-extensions`, use the following or leave blank (default): + + ```yaml + plugins: + - codeinclude: + title_mode: pymdownx.tabbed + ``` + + b. For version 7.x or lower of `pymdown-extensions`, use the following: + ```yaml + plugins: + - codeinclude: + title_mode: legacy_pymdownx.superfences + ``` + + c. If no tabbed fences should be used at all: + ```yaml + plugins: + - codeinclude: + title_mode: none + ``` + +## Usage + +A codeinclude block resembles a regular markdown link surrounded by a pair of XML comments, e.g.: + +<!-- +To prevent this from being rendered as a codeinclude when rendering this page, we use HTML tags. +See this in its rendered form to understand its actual appearance, or look at other pages in the +docs. +--> + +<pre><code><!--codeinclude--> +[Human readable title for snippet](./relative_path_to_example_code.java) targeting_expression +<!--/codeinclude--> +</code></pre> + +Where `targeting_expression` could be: + +* `block:someString` or +* `inside_block:someString` + +If these are provided, the macro will seek out any line containing the token `someString` and grab the next curly brace +delimited block that it finds. `block` will grab the starting line and closing brace, whereas `inside_block` will omit +these. If no `targeting_expression` is provided, the whole file is included. + +e.g., given: +```java + +public class FooService { + + public void doFoo() { + foo.doSomething(); + } + +} +``` + +If we use `block:doFoo` as our targeting expression, we will have the following content included into our page: + +```java +public void doFoo() { + foo.doSomething(); +} +``` + +Whereas using `inside_block:doFoo` we would just have the inner content of the method included: + +```java +foo.doSomething(); +``` + +Note that: + +* Any code included will be have its indentation reduced +* Every line in the source file will be searched for an instance of the token (e.g. `doFoo`). If more than one line + includes that token, then potentially more than one block could be targeted for inclusion. It is advisable to use a + specific, unique token to avoid unexpected behaviour. + +When we wish to include a section of code that does not naturally appear within braces, we can simply insert our token, +with matching braces, in a comment. +While a little ugly, this has the benefit of working in any context, even in languages that do not use +curly braces, and is easy to understand. +For example: + +```java +public class FooService { + + public void boringMethod() { + doSomethingBoring(); + + // doFoo { + doTheThingThatWeActuallyWantToShow(); + // } + } + +} +``` + +will be rendered as: + +```java +doTheThingThatWeActuallyWantToShow(); +``` + +## Building the Project + +Install the dependencies: + +```shell +pip install -r requirements.txt +pip install pytest # install pytest to run the tests +``` + +### Running tests + +To run the tests: +```shell +pytest +``` + +### Formatting code + +Code is formatted with Black. To apply formatting: +```shell +black codeinclude tests +``` + + + + +%package -n python3-mkdocs-codeinclude-plugin +Summary: A plugin to include code snippets into mkdocs pages +Provides: python-mkdocs-codeinclude-plugin +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-mkdocs-codeinclude-plugin +# mkdocs-codeinclude-plugin + +A plugin for mkdocs that allows some advanced 'includes' functionality to be used for embedded code blocks. +This is effectively an extended Markdown format, but is intended to degrade gracefully when rendered with a different renderer. + +## Installation + +1. Install the plugin: + + ``` + pip install mkdocs-codeinclude-plugin + ``` + +2. Add `codeinclude` to the list of your MkDocs plugins (typically listed in `mkdocs.yml`): + + ```yaml + plugins: + - codeinclude + ``` + +3. The plugin should be configured use an appropriate form of tabbed fences, depending on the version of +[`pymdown-extensions`](https://github.com/facelessuser/pymdown-extensions) that is installed. +Tabbed fences provide a 'title' for code blocks, and adjacent code blocks will appear as a multi-tabbed code block. + + a. For version 8.x of `pymdown-extensions`, use the following or leave blank (default): + + ```yaml + plugins: + - codeinclude: + title_mode: pymdownx.tabbed + ``` + + b. For version 7.x or lower of `pymdown-extensions`, use the following: + ```yaml + plugins: + - codeinclude: + title_mode: legacy_pymdownx.superfences + ``` + + c. If no tabbed fences should be used at all: + ```yaml + plugins: + - codeinclude: + title_mode: none + ``` + +## Usage + +A codeinclude block resembles a regular markdown link surrounded by a pair of XML comments, e.g.: + +<!-- +To prevent this from being rendered as a codeinclude when rendering this page, we use HTML tags. +See this in its rendered form to understand its actual appearance, or look at other pages in the +docs. +--> + +<pre><code><!--codeinclude--> +[Human readable title for snippet](./relative_path_to_example_code.java) targeting_expression +<!--/codeinclude--> +</code></pre> + +Where `targeting_expression` could be: + +* `block:someString` or +* `inside_block:someString` + +If these are provided, the macro will seek out any line containing the token `someString` and grab the next curly brace +delimited block that it finds. `block` will grab the starting line and closing brace, whereas `inside_block` will omit +these. If no `targeting_expression` is provided, the whole file is included. + +e.g., given: +```java + +public class FooService { + + public void doFoo() { + foo.doSomething(); + } + +} +``` + +If we use `block:doFoo` as our targeting expression, we will have the following content included into our page: + +```java +public void doFoo() { + foo.doSomething(); +} +``` + +Whereas using `inside_block:doFoo` we would just have the inner content of the method included: + +```java +foo.doSomething(); +``` + +Note that: + +* Any code included will be have its indentation reduced +* Every line in the source file will be searched for an instance of the token (e.g. `doFoo`). If more than one line + includes that token, then potentially more than one block could be targeted for inclusion. It is advisable to use a + specific, unique token to avoid unexpected behaviour. + +When we wish to include a section of code that does not naturally appear within braces, we can simply insert our token, +with matching braces, in a comment. +While a little ugly, this has the benefit of working in any context, even in languages that do not use +curly braces, and is easy to understand. +For example: + +```java +public class FooService { + + public void boringMethod() { + doSomethingBoring(); + + // doFoo { + doTheThingThatWeActuallyWantToShow(); + // } + } + +} +``` + +will be rendered as: + +```java +doTheThingThatWeActuallyWantToShow(); +``` + +## Building the Project + +Install the dependencies: + +```shell +pip install -r requirements.txt +pip install pytest # install pytest to run the tests +``` + +### Running tests + +To run the tests: +```shell +pytest +``` + +### Formatting code + +Code is formatted with Black. To apply formatting: +```shell +black codeinclude tests +``` + + + + +%package help +Summary: Development documents and examples for mkdocs-codeinclude-plugin +Provides: python3-mkdocs-codeinclude-plugin-doc +%description help +# mkdocs-codeinclude-plugin + +A plugin for mkdocs that allows some advanced 'includes' functionality to be used for embedded code blocks. +This is effectively an extended Markdown format, but is intended to degrade gracefully when rendered with a different renderer. + +## Installation + +1. Install the plugin: + + ``` + pip install mkdocs-codeinclude-plugin + ``` + +2. Add `codeinclude` to the list of your MkDocs plugins (typically listed in `mkdocs.yml`): + + ```yaml + plugins: + - codeinclude + ``` + +3. The plugin should be configured use an appropriate form of tabbed fences, depending on the version of +[`pymdown-extensions`](https://github.com/facelessuser/pymdown-extensions) that is installed. +Tabbed fences provide a 'title' for code blocks, and adjacent code blocks will appear as a multi-tabbed code block. + + a. For version 8.x of `pymdown-extensions`, use the following or leave blank (default): + + ```yaml + plugins: + - codeinclude: + title_mode: pymdownx.tabbed + ``` + + b. For version 7.x or lower of `pymdown-extensions`, use the following: + ```yaml + plugins: + - codeinclude: + title_mode: legacy_pymdownx.superfences + ``` + + c. If no tabbed fences should be used at all: + ```yaml + plugins: + - codeinclude: + title_mode: none + ``` + +## Usage + +A codeinclude block resembles a regular markdown link surrounded by a pair of XML comments, e.g.: + +<!-- +To prevent this from being rendered as a codeinclude when rendering this page, we use HTML tags. +See this in its rendered form to understand its actual appearance, or look at other pages in the +docs. +--> + +<pre><code><!--codeinclude--> +[Human readable title for snippet](./relative_path_to_example_code.java) targeting_expression +<!--/codeinclude--> +</code></pre> + +Where `targeting_expression` could be: + +* `block:someString` or +* `inside_block:someString` + +If these are provided, the macro will seek out any line containing the token `someString` and grab the next curly brace +delimited block that it finds. `block` will grab the starting line and closing brace, whereas `inside_block` will omit +these. If no `targeting_expression` is provided, the whole file is included. + +e.g., given: +```java + +public class FooService { + + public void doFoo() { + foo.doSomething(); + } + +} +``` + +If we use `block:doFoo` as our targeting expression, we will have the following content included into our page: + +```java +public void doFoo() { + foo.doSomething(); +} +``` + +Whereas using `inside_block:doFoo` we would just have the inner content of the method included: + +```java +foo.doSomething(); +``` + +Note that: + +* Any code included will be have its indentation reduced +* Every line in the source file will be searched for an instance of the token (e.g. `doFoo`). If more than one line + includes that token, then potentially more than one block could be targeted for inclusion. It is advisable to use a + specific, unique token to avoid unexpected behaviour. + +When we wish to include a section of code that does not naturally appear within braces, we can simply insert our token, +with matching braces, in a comment. +While a little ugly, this has the benefit of working in any context, even in languages that do not use +curly braces, and is easy to understand. +For example: + +```java +public class FooService { + + public void boringMethod() { + doSomethingBoring(); + + // doFoo { + doTheThingThatWeActuallyWantToShow(); + // } + } + +} +``` + +will be rendered as: + +```java +doTheThingThatWeActuallyWantToShow(); +``` + +## Building the Project + +Install the dependencies: + +```shell +pip install -r requirements.txt +pip install pytest # install pytest to run the tests +``` + +### Running tests + +To run the tests: +```shell +pytest +``` + +### Formatting code + +Code is formatted with Black. To apply formatting: +```shell +black codeinclude tests +``` + + + + +%prep +%autosetup -n mkdocs-codeinclude-plugin-0.2.1 + +%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-codeinclude-plugin -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Thu May 18 2023 Python_Bot <Python_Bot@openeuler.org> - 0.2.1-1 +- Package Spec generated @@ -0,0 +1 @@ +9c33a06ad5c3719c5afcc54e83312e9c mkdocs-codeinclude-plugin-0.2.1.tar.gz |