orgweb
is intended for developers that want to create literate programming
project using Org-mode, but that does not want to invest time to learn how to
use Emacs and Org-mode. If you are a developer that already uses Emacs and
Org-mode, this tool is most likely not for you, but maybe for the people on your
team that doesn’t know, nor want to know, Emacs.
orgweb
is a very simple CLI tool that does the following:
-
tangle
one or multiple Org files -
detangle
one or multiple source files -
execute
one or multiple Org files -
monitor
file changes on the file system to automaticallytangle
anddetangle
files that changes.
What is Literate Programming? Why?
If you wonder what a Literate Programming project looks like, just poke around this repository to have a glimpse of the potential.
orgweb
is designed in a way that developers can use all the power of Org-mode,
in any IDE they like, without having to rely on Emacs directly.
To do that, it leverages Docker to build an image where Emacs is properly installed and configured to implement the commands that are exposed via the command line tool.
If the orgweb
docker image is not currently existing in the environment, then
it will request Docker to build the image using the Dockerfile. The build
process will install and configure all the components required to implement all
orgweb
commands.
orgweb
check if it exists every time it is invoked from the command line. This
process will happen any time that the image is not available in the environment.
If the image is existing in the environment, then the following will happen.
orgweb
will ask Docker to create a container based on the image. Once the
container is running, it will execute a command on the container’s terminal to
run Emacs. Emacs is used directly from the command line by evaluating ELisp code
it gets as input.
Every time a orgweb
command line is executed, a new container is created:
If Docker is already installed in your development environment, you can skip this step. Otherwise, you should install Docker.
To install Docker Desktop, you simply have read and follow those instructions.
orgweb
is available on PyPi, you can easily install it locally by running the
following command in your terminal:
pip install orgweb
If you want to improve and contribute to the project, you will first have to
generate the sources files from the Org mode files in the repository. To do so,
you will need orgweb
itself (installed in the previous step), or you could do
the same if you have a local Emacs instance configured with org-mode
. But
let’s assumes you don’t.
First clone the repository in your environment:
git clone https://github.com/fgiasson/orgweb.git
Once the repository is cloned, let’s tangle all the files:
cd orgweb
orgweb tangle .
These commands will tangle all the sources and configuration files required by the project.
Once they have been tangle, you will be able to use make to create the development environment and the package to run locally.
make create-venv # create the pyenv virtual environment
source .venv/bin/activate # source that environment
make install-build # install Python's build
make build # build the orgweb CLI application
make install-local-build # install the package we just created
After that, you will be able to run make rebuid-local
every time you want to
test some changes you made to the application.
Each of the operation work with the same folder structure assumption. There are three main components:
- folder
- files
The folder
is a where the files
are located, within the project folder
.
The files
is a list of one or multiple files we want to tangle.
orgweb tangle
takes a folder
as input. The folder
is where the Org files
we want to tangle are located. The operation is recursive, it will check in all
subfolders of folder
Optionally, one or multiple files can be listed. Those files are located in
folder
, and those are the ones that will be tangled from that folder.
If no file is mentioned, then all the Org files from folder
will be tangled.
cd /my/project/folder/
orgweb tangle . --file=foo.org --file=bar.org
In that example, orgweb
will tangle the two files /my/project/folder/foo.org
and /my/project/folder/bar.org
orgweb detangle
takes a folder
as input. The folder
is where the source
files we want to detangle are located. The operation is recursive, it will check in all
subfolders of folder
Optionally, one or multiple files can be listed. Those files are located in
folder
, and those are the ones that will be detangled from that folder.
If no file is mentioned, then all the Org files from folder
will be detangled.
The detangle
command does make sure that an input source file is a file that
was previously tangled. Otherwise, it will be ignored. It does so by checking
the tangling markup in comments of the source file.
cd /my/project/folder/
orgweb detangle . --file=foo.py --file=bar.py
In that example, orgweb
will detangle the two files
/my/project/folder/foo.py
and /my/project/folder/bar.py
orgweb execute
takes a folder
as input. The folder
is where the Org files
we want to execute are located. The operation is recursive, it will check in all
subfolders of folder
Optionally, one or multiple files can be listed. Those files are located in
folder
, and those are the ones that will be executed from that folder.
If no file is mentioned, then all the Org files from folder
will be executed.
The execute
command is used to execute every code block or the Org files. This
is normally used to execute PlantUML code blocks such that it produces graphs
that are referrenced within Org files.
cd /my/project/folder/
orgweb execute . --file=foo.org
In that example, orgweb
will execute the /my/project/folder/foo.py
orgweb monitor
will take a folder as input and will monitor every file changes
in that directory, recursively. If a Org file changes, it will be tangled, if a
source file changes it will be detangled.
Monitoring is used to make sure that the Org files and their source files are always in sync, without having the developers to carefully tangle and detangle every time they modify a file.
cd /my/project/folder/
orgweb monitor .
Let’s take some time to cover the different tangling workflows that you may imagine.
The first scenario is when you have a single Org file that tangles code blocks in one, or multiple, source files, such as:
This is the workflow that is currently implemented in Org-mode. You can tangle a
foo.org
file in as many source files you want. Then, if you just detangle
Foo.py
, then only the code blocks with that code will be updated in Foo.org
.
Then you could extrapolate this case and think about the following scenario:
This scenario is when you have two different Org files that tangle in the same
source file. Then, when you detangle FooBar.py
, you would imagine that each
blocks would detangle in their respective Org file.
However, this is not currently the case with Org mode. This scenario is currently not supported and will break your literate programming workkflow.
Another thing to take care of is that the noweb syntax is not currently supported for the detangle command. This is a long standing issue with Org-mode that is discussed for several years now.
You can use noweb
only if you won’t detangle
your source files.
We welcome contributions to OrgWeb! If you’d like to contribute, please follow these steps:
- Fork the repository on GitHub.
- Create a new branch with a descriptive name:
git checkout -b feature/your-feature-name
- Push your changes to your fork:
git push origin feature/your-feature-name
- Make your changes and commit them:
git commit -m "Add feature: your feature name"​
- Submit a pull request to the main branch of the original repository.
- Make sure that you only commit the Org-mode files, and not the source files
themselves. Add them to the
make clean
method if needed.