entangled / mkdocs-plugin

An MkDocs plugin that lets you do Literate Programming through Entangled.

Welcome to MkDocs Entangled Plugin

Using this plugin, you can make your Entangled documents look better.

Examples

Detailed examples are found in the entangled/mkdocs-examples repository.

Install

Install this with pip install mkdocs-entangled-plugin. To use the entangled plugin, add the following lines to your mkdocs.yml:

plugins:
  - entangled

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true 

For more information, see the documentation.

Components

This plugin bundles functionality for literate programming with Entangled.

• Annotate code blocks with titles.
• Build artifacts using Make.

Annotate code blocks

The default markdown syntax that Entangled supports has fenced code blocks as follows

``` {.python file=examples/hello_world.py}
if __name__ == "__main__":
    <<hello-world>>
```

Which renders like this:

if __name__ == "__main__":
    <<hello-world>>

Or named code blocks

``` {.python #hello-world}
print("Hello, World!")
```

that render like this:

print("Hello, Universe!")

Build Artifacts

Build artifacts by specifying a Makefile.

=== "Figure 1"

    ![](fig/plot.svg)

=== "Source"

    ``` {.gnuplot file=examples/plot.gp}
    # enter your plotting commands here
    ```

    ``` {.make .build-artifact}
    .RECIPEPREFIX = >
  
    docs/fig/plot.svg: examples/plot.gp
    > mkdir -p $(@D)
    > gnuplot $^ > $@
    ```

=== "Figure 1"

![](fig/plot.svg)

=== "Source"

``` {.gnuplot file=examples/plot.gp}
set term svg background rgb 'white' size 700, 500
sinc(r) = sin(pi*r) / (pi*r)
set isosamples 50, 50
set hidden3d
set xrange [-4:4]
set yrange [-4:4]
set xyplane 0
set title "Sinc function"
splot sinc(sqrt(x**2 + y**2)) t'' lc rgb '#5533cc'
```

``` {.make .build-artifact}
.RECIPEPREFIX = >

docs/fig/plot.svg: examples/plot.gp
> mkdir -p $(@D)
> gnuplot $^ > $@
```

License

Licensed under the Apache-2 license agreement: see LICENSE

mkdocs-plugin's Issues

toml code type removes file data

when i tried to document a usage example of setuptools_scm,

i added the fence

{ .toml title="pyproject.toml" file="docs/examples/version_scheme_code/pyproject.toml" }
and observed no file created

after i changed it to { .python title="pyproject.toml" file="docs/examples/version_scheme_code/pyproject.toml" } i observed a file being created

its not quite clear to me what im missing there