Lightweight documentation generator
Project description
📰 Edition
WARNING: This is a pre-release project.
Edition is a command-line application for creating beautiful HTML and Markdown editions of your projects' documentation.
In fact, the document you're reading right now was pressed by Edition.
✨ Highlights
- Write your documentation once.
Edition will give you anREADME.md
to upload to your project, PyPI and all the rest, and a beautiful HTML page ready to upload directly to GitHub or GitLab Pages. - Works out of the box.
With one command, your existingREADME.md
can be converted to beautiful HTML. - Embed your code samples.
Edition will execute your code and embed the results.
✋ Example
Create this Markdown document named example-source.md
:
# Edition example
Save this file to your local machine as `example-source.md`
then run:
```bash
edition example-source.md example.html --press html
```
Now open `example.html` in a web browser. The code example
below will be complete.
```bash
python --version
```
<!--edition-exec-->
Run:
python -m edition docs/example-source.md docs/example.html --press html
warn: no value for author
warn: no value for favicon-emoji
This will generate example.html. Open that file in a web browser.
🤔 Is Edition right for you?
Edition could be great for you if:
- You've tried other documentation tools and they were more complex or time-consuming than you care for
- Your documentation fits on a single page
Edition is not a feature-matching substitute for Sphinx, mkdocs, pdoc or the like, nor is Edition aiming to be.
If you need multi-page documentation, docstring parsing or fine configuration then Edition is not right for you.
⚙️ Getting Started
Edition requires Python 3.8 or later.
Install Edition via pip
:
pip install edition
📄 Creating your source document
Your source document is the Markdown document from which all your editions will be pressed.
Any Markdown document you already have -- like your project's README.md
-- is already a valid source document, but we can add some front matter and additional markup to help guide the presses.
Front matter
The following front matter properties come into play only when pressing HTML.
Property | Description | Default |
---|---|---|
author | Author name | No author |
favicon-emoji | Emoji to use as favicon | No favicon |
title | Page title | Top-level heading |
For example:
---
author: Cariad Eccleston
favicon-emoji: 🍕
# If "title" was omitted then the top-level "Example"
# heading would be used instead:
title: Embedded Example
---
# Example
Markup
Code execution
To have Edition execute your code then embed the result:
- Create a regular Markdown code block
- Add
<!--edition-exec-->
after the block
For example:
```python
print("Hello, world!")
```
<!--edition-exec-->
Currently only bash
and python
code blocks are supported. More languages can be added if they are requested.
Table of Contents
<edition value="toc" />
🍰 Contributing
Thank you for considering contribution!
To contribute a bug report, enhancement or feature request, please raise an issue at github.com/cariad/edition/issues.
If you want to contribute a code change, please raise an issue first so we can chat about the direction you want to take.
👮♀️ Licence
Edition is released at github.com/cariad/edition under the MIT Licence.
See LICENSE for more information.
👩💻 The Author
Hello! 👋 I'm Cariad Eccleston and I'm a freelance DevOps and backend engineer. My contact details are available on my personal wiki at cariad.earth.
Please consider supporting my open source projects by sponsoring me on GitHub.
🔗 Related Projects
- Epic thanks to John Gruber for releasing the Markdown specification.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for edition-1.0.0a2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3574c1b850005956d5c18a2fac4357b9bc2c260d8defd1cee1125e3bb2eade52 |
|
MD5 | d613500eb743bcc7387d3b85058592ca |
|
BLAKE2b-256 | 5b7ee78b6782b7a71544f79e9a8c5fd83850b61f7124ce065c6022efec0782f9 |