95 lines
3.5 KiB
Markdown
Executable File
95 lines
3.5 KiB
Markdown
Executable File
# onPoint
|
||
|
||
Yet another markdown-based presentation tool. onPoint statically generates presentations in HTML based on Markdown content. Slide layouts can be configured via simple HTML templates.
|
||
|
||
## Installation
|
||
|
||
This program is meant to be used as a git submodule of your actual presentation project, therefore you need to add it:
|
||
|
||
```sh
|
||
git submodule add -b release git@git.stuve-bamberg.de:latex/onpoint.git
|
||
```
|
||
|
||
Make sure to have python3 and pandoc (the same version for all developers!) installed.
|
||
Next, we can install all requirements:
|
||
|
||
```sh
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
cd onpoint
|
||
pip3 install -r requirements.txt
|
||
```
|
||
|
||
To compile, run `python3 main.py $root_directory`. Use `python3 main.py -h` to learn more about all available optional parameters.
|
||
|
||
**Note for onpoint developers:** You will have to pass `--no-help-menu` to compile the slides in the `demo` folder of this development repository.
|
||
|
||
## The Project Structure
|
||
|
||
We recommend you to structure your project directory like this:
|
||
|
||
├── images
|
||
├── layouts
|
||
│ ├── default.html
|
||
│ ├── root.html
|
||
│ └── titlepage.html
|
||
├── meta.yml
|
||
├── legal.yml
|
||
├── onpoint
|
||
│ ├── autocompile.sh
|
||
│ ├── main.py
|
||
│ ├── ….py
|
||
│ ├── README.md
|
||
│ └── requirements.txt
|
||
├── slides
|
||
│ ├── chapter1.de.md
|
||
│ ├── chapter1.en.md
|
||
│ ├── chapter2.de.md
|
||
│ └── chapter2.en.md
|
||
├── slides.de.html
|
||
├── slides.en.html
|
||
├── slides.yml
|
||
└── styles
|
||
└── style.css
|
||
|
||
* `onpoint` is where this program lives.
|
||
* In `layouts`, you can create custom templates for your slides.
|
||
* `meta.yml` is there to add language-specific meta information (like title internationalization).
|
||
* `legal.yml` contains links to the privacy policy and imprint that ought to be rendered into the help menu.
|
||
* `slides.yml` will contain a list of all chapters to be included. Their content is expected to live in files inside the `slides` folder.
|
||
* You can store your usual web resources in the folders `styles` and `images`.
|
||
|
||
## Updating onPoint
|
||
|
||
In order to update the version of onPoint in an existing project, simply enter the `onpoint` directory and run `git pull`.
|
||
|
||
## Auto-compile during Development
|
||
|
||
You might want to have all slides auto-compiled for you on safe. For this case, we wrote a small bash script that spawns a file watcher to compile your presentation once any markdown file in the slides folder is saved. Simply run `./onpoint/autocompile.sh` from your project root folder.
|
||
|
||
You will need Python and `inotify-tools` to execute the script.
|
||
|
||
## Troubleshooting
|
||
|
||
### Missing packages
|
||
|
||
Error message (example):
|
||
|
||
Collecting lxml==5.2.0 (from -r requirements.txt (line 2))
|
||
Using cached lxml-5.2.0.tar.gz (3.7 MB)
|
||
Installing build dependencies ... done
|
||
Getting requirements to build wheel ... error
|
||
error: subprocess-exited-with-error
|
||
|
||
× Getting requirements to build wheel did not run successfully.
|
||
│ exit code: 1
|
||
╰─> [4 lines of output]
|
||
<string>:67: DeprecationWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html
|
||
Building lxml version 5.2.0.
|
||
Building without Cython.
|
||
Error: Please make sure the libxml2 and libxslt development packages are installed.
|
||
|
||
Make sure to install the following packages:
|
||
|
||
+ Ubuntu: `libxml2-dev`, `libxslt-dev`, `python-dev`, `gcc`, `pandoc`
|
||
+ Fedora: `libxml2-devel`, `libxslt-devel`, `python-devel`, `gcc`, `pandoc` |