path: root/python-mkdocs-codeinclude-plugin.spec

%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>&lt;!--codeinclude--&gt;
[Human readable title for snippet](./relative_path_to_example_code.java) targeting_expression
&lt;!--/codeinclude--&gt;
</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>&lt;!--codeinclude--&gt;
[Human readable title for snippet](./relative_path_to_example_code.java) targeting_expression
&lt;!--/codeinclude--&gt;
</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>&lt;!--codeinclude--&gt;
[Human readable title for snippet](./relative_path_to_example_code.java) targeting_expression
&lt;!--/codeinclude--&gt;
</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