org-template-builder 0.1.0

Python Org-Mode Template Builder.

Org-template-builder

pip install org-template-builder

python -m orgtemp myprojectname --author myname

The orgtemp process will raise an exception if the directory is not empty. It won’t exit if it contains dotfiles, like .git or .projectile. This means that the best way to use it is the following.

mkdir myprojectname && cd myprojectname && python -m orgtemp myprojectname

This behaviour is to protect (in case of user mistake) overwriting existing configurations from other org-template-builder projects, individual checking/versioning/uninstalling has not been implemented.

The template will attempt to initialize a git repo with the subprocess module and add submodules to it but it won’t make any commits. It will attempt to create and checkout a branch named main, to avoid using the default master name.

Template Builder Arguments

Project Name

Whenever org-template-builder installs all the parts, it will use whatever =--project= name was given to it to modify the default of a few files:

1. The first .org file’s name.
2. The title and first header of the same file.
3. The PROJECT_NAME variable in the Makefile.
4. All references to PROJECT_NAME files in the Makefile.

However, when copying the “project named” .md file to the root directory, Makefile will rename it to README.md.

If no project name is given, it will be set to readme.

Author Name

The author name argument is optional, defaults to "" and it is only added to the header of the .org file with the name of the project.

Introduction

This is an org-mode template for literate programming. The HTML theme is a fork of https://github.com/fniessen/org-html-themes.

The Makefile options are:

1. make update will go over all submodules and pull any changes.
2. make should call tangle.el and publish.el without force, which renders all the HTML and Markdown and copies all the static files to public.
3. make clean should remove all directories in public before running a force version of publish.
4. make commit should run publish (non-forced) and then add and commit with automated timestamp.

make update

make

make clean

..
├── config
├── docs
├── public
│   ├── build
│   └── resources
│       ├── images
│       ├── installer
│       │   └── config
│       └── theme
│           ├── css
│           ├── js
│           └── lib
│               └── js
├── resources
│   ├── data
│   ├── images
│   └── theme
│       ├── css
│       ├── js
│       └── lib
│           └── js
├── src
└── tests

23 directories

1. Public: HTML directory for web.
   • Resources: Copies of all files from root/resources specified on publish.el.
   • Build: This is the equivalent of the src directory but for the HTML renders.
2. Resources: All static files, plus the theme submodule from org-theme repository.
3. Docs: The equivalent of src but for Markdown renders.
4. Src: Where all org and tangled code files live.
5. Tests: Reserved for writing tests with our without org files.

All files in resources that match the types specified in publish.el will be copied to /public/resources.

Having the src and build folders at the same tree level helps when accessing the equivalent resources folder from either directory.

Code Examples

Shell Example

Shell source blocks don’t tangle as they are normally one liners. This particular line just sets the local Python environment via pyenv, I don’t need a venv for this demo.

We must make sure that :dir is set to the parent directory ...

pyenv local 3.7.13 && cat .python-version

3.7.13

Now let’s install a Python library with pip. Once ran, we are setting this block to :eval no.

This is where we would use poetry or activate or venv.

pip install tabulate && pip list | grep tabulate

SQL Example

This is an SQL query for the database specified in the org-header.config file, which is the pagila sample database. For changing the sql info it’s always better to override the header-args in the current document while using the original configuration as reference.

SELECT
	CONCAT(customer.last_name, ', ', customer.first_name) AS customer,
	address.phone,
	film.title
FROM
	rental
	INNER JOIN customer ON rental.customer_id = customer.customer_id
	INNER JOIN address ON customer.address_id = address.address_id
	INNER JOIN inventory ON rental.inventory_id = inventory.inventory_id
	INNER JOIN film ON inventory.film_id = film.film_id
WHERE
	rental.return_date IS NULL
	AND rental_date < CURRENT_DATE
ORDER BY
	title
LIMIT 5;

customer	phone	title
OLVERA, DWAYNE	62127829280	ACADEMY DINOSAUR
HUEY, BRANDON	99883471275	ACE GOLDFINGER
OWENS, CARMEN	272234298332	AFFAIR PREJUDICE
HANNON, SETH	864392582257	AFRICAN EGG
COLE, TRACY	371490777743	ALI FOREVER

Elisp Example

Elisp blocks do not tangle by default either as they are mostly functions to evaluate on-the-go while using emacs.

(run-python)

(emacs-version)

GNU Emacs 28.1 (build 1, x86_64-apple-darwin18.7.0, NS appkit-1671.60 Version 10.14.6 (Build 18G95))
 of 2022-05-11

Python Example

Python uses a session, as specified in the ../config/org-header.config, so there must be a (run-python) session running.

print("TODO: finish this part.")

TODO: finish this part.

Admonitions

Support for HTML export admonitions. Four colors for a few options.

This is a note.

This is a hint.

This is a caution.

This is a warning.