Package: orgweb
Table of ContentsHow does it work?InstallingDockerFrom PackageFrom SourceUsageFolder StructureTangleDetangleExecuteMonitorTangling WorkflowsContributionsorgwebis intended for developers that want to create literate programming
project using Org-mode, but thatdoes notwant to investing 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, about Emacs.orgwebis a very simple CLI tool that does the following:tangleone or multiple Org filesdetangleone or multiple source filesexecuteone or multiple Org filesmonitorfile changes on the file system to automaticallytangleanddetanglefiles 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 glimps of the potential.How does it work?orgwebis 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 theorgwebdocker 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 allorgwebcommands.orgwebcheck 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.orgwebwill 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 aorgwebcommand line is executed, a new container is created:InstallingDockerIf 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.From Packageorgwebis available on PyPi, you can easily install it locally by running the
following command in your terminal:pip install orgwebFrom SourceIf 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 needorgwebitself (installed in the previous step), or you could do
the same if you have a local Emacs instance configured withorg-mode. But
let's assumes you don't.First clone the repository in your environment:git clone https://github.com/fgiasson/orgweb.gitOnce 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
make install-build        # install Python's build
source .venv/bin/activate # source that environment
make build                # build the orgweb CLI application
make install-local-build  # install the package we just createdAfter that, you will be able to runmake rebuid-localevery time you want to
test some changes you made to the application.UsageFolder StructureEach of the operation work with the same folder structure assumption. There are three main components:folderfilesThefolderis a where thefilesare located, within theproject folder.Thefilesis a list of one or multiple files we want to tangle.Tangleorgweb tangletakes afolderas input. Thefolderis where the Org files
we want to tangle are located. The operation is recursive, it will check in all
subfolders offolderOptionally, one or multiple files can be listed. Those files are located infolder, and those are the ones that will be tangled from that folder.If no file is mentioned, then all the Org files fromfolderwill be tangled.cd /my/project/folder/
orgweb tangle . --file=foo.org --file=bar.orgIn that example,orgwebwill tangle the two files/my/project/folder/foo.organd/my/project/folder/bar.orgDetangleorgweb detangletakes afolderas input. Thefolderis where the source
files we want to detangle are located. The operation is recursive, it will check in all
subfolders offolderOptionally, one or multiple files can be listed. Those files are located infolder, and those are the ones that will be detangled from that folder.If no file is mentioned, then all the Org files fromfolderwill be detangled.Thedetanglecommand 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.pyIn that example,orgwebwill detangle the two files/my/project/folder/foo.pyand/my/project/folder/bar.pyExecuteorgweb executetakes afolderas input. Thefolderis where the Org files
we want to execute are located. The operation is recursive, it will check in all
subfolders offolderOptionally, one or multiple files can be listed. Those files are located infolder, and those are the ones that will be executed from that folder.If no file is mentioned, then all the Org files fromfolderwill be executed.Theexecutecommand 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.orgIn that example,orgwebwill execute the/my/project/folder/foo.pyMonitororgweb monitorwill 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 .Tangling WorkflowsLet'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 afoo.orgfile in as many source files you want. Then, if you just detangleFoo.py, then only the code blocks with that code will be updated inFoo.org.Then you could extrapolite 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 detangleFooBar.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 thenoweb 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 usenowebonly if you won'tdetangleyour source files.ContributionsWe 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-namePush your changes to your fork:git push origin feature/your-feature-nameMake 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 themake cleanmethod if needed.