Metadata-Version: 2.1
Name: org-template-builder
Version: 0.1.0
Summary: Python Org-Mode Template Builder.
License: MIT
Author: AlbertoV5
Author-email: 58243333+AlbertoV5@users.noreply.github.com
Requires-Python: >=3.7,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Dist: requests (==2.28.1)
Description-Content-Type: text/markdown

# Org-template-builder

```shell
pip install org-template-builder
```

```shell
python -m orgtemp myprojectname --author myname
```

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

```shell
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&rsquo;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&rsquo;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 &ldquo;project named&rdquo; `.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.

```shell
make update
```

```shell
make
```

```shell
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.

![img](../resources/images/emacs.png "Emacs logo")


# Code Examples


## Shell Example

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

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

```shell
pyenv local 3.7.13 && cat .python-version
```

    3.7.13

Now let&rsquo;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`.

```shell
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&rsquo;s always better to override the `header-args` in the current document while using the original configuration as reference.

```sql
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.

```elisp
(run-python)
```

```elisp
(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.

```python
print("TODO: finish this part.")
```

    TODO: finish this part.


# Admonitions

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

<div class="note" id="orgf1b6be7">
<p>
This is a note.
</p>

</div>

<div class="hint" id="org6d50e2c">
<p>
This is a hint.
</p>

</div>

<div class="caution" id="org82d220f">
<p>
This is a caution.
</p>

</div>

<div class="warning" id="orgc6e0981">
<p>
This is a warning.
</p>

</div>

