Intro
Instead of changing CSS style for Your Racket projects documentation, You may be interested in compiling Markdown files generated form Scribble source into HTML documentation website.
Creating MkDocs project
-
Create docs
directory and mkdocs.yml
config file in current directory, along with a dummy index.md
file in docs
folder.
-
Edit the name of the project.
Replace Racket-Project
with your project name.
|
---
site_name: Racket-Project
|
Building Scribble
Generate markdown files form scribble documentation.
Replace Racket-Project.scrbl
with path to your scribble documentation main source file.
|
scribble --markdown --dest ./docs --dest-name index.md Racket-Project.scrbl
|
Building Markdown
Compile HTML documentation from the markdown source.
HTML files should appear in the site
directory.
Running the server
Some features, like search for example are only available when running the mkdocs server.
Caveats
Some scribble functions do not look good or work correctly for markdown-to-HTML compilation by MkDocs.
Example configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 |
site_name: Racket-Ebuild
site_author: xgqt@riseup.net
site_description: library to ease ebuild creation
site_url: https://gitlab.com/gentoo-racket/racket-ebuild
repo_name: gentoo-racket/racket-ebuild
repo_url: https://gitlab.com/gentoo-racket/racket-ebuild
plugins:
- search
theme:
name: material
extra:
social:
- icon: fontawesome/brands/gitlab
link: https://gitlab.com/gentoo-racket/racket-ebuild
|
Preparation
First using a needle or a toothpick click a button on the right side of the laptop (indicated by a bent arrow), this will start the machine up in BIOS selection menu where you choose the BIOS setup option.
Then, in the BIOS menu disable option to check laptop charge level while it is shut down. If not disabled it will interfere with key combination that has to be pressed while laptop is shut down. This can be turned back after the advanced BIOS menu is enabled.
After that "Exit saving changes" and shutdown.
Keys
I thought it was a joke at first but it really is true that a special combination of keys has to be pressed depending on the laptop model (while it is shut down).
For my laptop it is as follows:
|
F4 4 r f v
F5 5 t g b
F6 6 y h n
|
References
Template
File: /etc/systemd/system/APP.service
1
2
3
4
5
6
7
8
9
10
11
12 |
[Unit]
Description=Run APP application
[Service]
Type=simple
ExecStart=/usr/bin/LANG APP_DIR/APP APP_ARGS
Restart=on-failure
User=root
WorkingDirectory=APP_DIR
[Install]
WantedBy=multi-user.target
|
Also, the application might need to reference a PID file, let systemD know abut it via PIDFile
.
Example
File: /etc/systemd/system/julia_dash_app.service
1
2
3
4
5
6
7
8
9
10
11
12 |
[Unit]
Description=Run Julia Dash application
[Service]
Type=simple
ExecStart=/usr/bin/julia /root/julia_dash_app/main.jl
Restart=on-failure
User=root
WorkingDirectory=/root/julia_dash_app
[Install]
WantedBy=multi-user.target
|
Potential benefits
Running tests
- test BEFORE (
src_test
) and AFTER (pkg_postinst
) installation
- test if and how services break if they are not reloaded
- test buildsystem configuration
- sandbox enforces strict and consistent build rules
- benchmarking with different compilation flags and libraries versions/releases
Configuration matrix
We can test across Cartesian product of different configuration settings, like:
- USE flags
- MAKEOPTS
- CFLAGS, CXXFLAGS, CPPFLAGS, LDFAGS, RUSTFLAGS, etc.
- arches (cross-compilation or run in qemu)
- static linking
- supported releases & versions of libraries (eg. glibc & musl)
Also, we could create diffs of installed files across different merges.
Reproducibility
- mini overlay with ::gentoo or any other (eg. company's own) as master
- record VCS (eg. git) hash of the dependent overlays
Binaries
- grab dependencies from binhosts
- distribute built binaries (maybe upload to a company's own artifacts server)
- make AppImages
Getting there
How do we run this?
Do we want to write a proper tool, which we probably do or do we just run Portage + shells scripts?
Do we want to run under root, user, in eprefix, maybe all in docker?
Configuration files
The .portci
directory contains the configuration.
Bug 799626
Link: bugs.gentoo.org/799626
Instead of using Ansible, Python, Yaml or Scheme we might use something similar to this for simple configuration, or if gets merged to upstream Portage the better.
Worth mentioning is the idea from Michał Górny who proposes to configure portage with toml files, like the example given in the bug report.
|
[package.unmask]
~virtual/libcrypt-2
[package.use.mask]
sys-libs/libxcrypt -system -split-usr
[package.use.force]
sys-libs/glibc -crypt
|
Also, package.x
+ Toml == a match made in heaven, it looks very nice!
Make gallery-dl work like youtube-dl
A configuration file to download everything into current directory, like yotube-dl does.
File: ~/.config/gallery-dl/config.json
|
{
"directory": [],
"base-directory": "./"
}
|