Package: org-template-builder
Org-template-builderTemplate Builder ArgumentsProject NameAuthor NameIntroductionFolder StructureDependenciesDefault theme and modulesRunning from a parent projectCode ExamplesShell ExampleSQL ExampleElisp ExamplePython ExampleTo DoFix the README file in the project root.AdmonitionsOrg-template-builderpipinstallorg-template-builderpython-morgtempmyprojectname--authormynameTheorgtempprocess will raise an exception if the directory is not empty. It won’t exit if it contains dotfiles, like.gitor.projectile. This means that the best way to use it is the following.mkdirmyprojectname&&cdmyprojectname&&python-morgtempmyprojectnameThis 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 thesubprocessmodule and add submodules to it but it won’t make any commits. It will attempt to create and checkout a branch namedmain, to avoid using the defaultmastername.Template Builder ArgumentsProject NameWheneverorg-template-builderinstalls all the parts, it will use whateverprojectnamewas given to it to modify the default of a few files:Create a.orgfile insrcand give it theprojectname.Set the title and first header of that file toprojectname.Set thePROJECT_NAMEvariable in theMakefile.However, when copying theprojectname.mdfile fromdocsto the root directory,Makefilewill rename it toREADME.md.If no project name is given, it will be set to “readme”.Author NameThe author name argument is optional, defaults to""and it is only added to the header of theprojectname.orgfile.IntroductionThis is an org-mode template for literate programming. The HTML theme is a fork ofhttps://github.com/fniessen/org-html-themes.The Makefile options are:make updatewill go over all submodules and pull any changes.makeshould calltangle.elandpublish.elwithoutforce, which renders all the HTML and Markdown and copies all the static files fromresourcestopublic.make cleanshould remove all directories inpublicbefore running aforceversion ofpublish.make commitshould runpublish(non-forced) and then add and commit with automated timestamp.makeupdatemakemakecleanFolder StructureThis is the structure from the root directory.tree..-I'venv|orgtemp'-d..
├── config
├── dist
├── docs
├── public
│   ├── build
│   └── resources
│       ├── images
│       └── theme
│           ├── css
│           ├── js
│           └── lib
│               └── js
├── resources
│   ├── images
│   └── theme
│       ├── css
│       ├── js
│       └── lib
│           └── js
├── src
└── tests
    └── __pycache__

22 directoriesPublic: HTML directory for web.Resources: Copies of all files from root/resources specified on publish.el.Build: This is the equivalent of thesrcdirectory but for the HTML renders.Resources: All static files, plus thethemesubmodule fromorg-themerepository.Docs: The equivalent ofsrcbut for Markdown renders.Src: Where all org and tangled code files live.Tests: Reserved for writing tests with our without org files.All files inresourcesthat match the types specified inpublish.elwill be copied to/public/resources.Having thesrcandbuildfolders at the same tree level helps when accessing the equivalentresourcesfolder from either directory.DependenciesThe two base dependencies are inconfigandresources/theme. They do not share the same parent directory so the user must be careful when assuming their paths. The reason is simply to separate directories that are copied topublic. So in case that there is any sensitive information inconfigwe are sure it is not by default copied topublic.The file types to copy to public from resources are specified in thepublish.elfiles anyway. And the.gitignoreincludes some paths inresourceslikeresources/keysthat at least won’t be commited. In case of storing keys in json, it is not included in the static files as of0.1.1.As of0.1.1, the static files are the following."ico\\|png\\|jpg\\|jpeg\\|gif\\|svg\\|html\\|css\\|js\\|txt"ico\|png\|jpg\|jpeg\|gif\|svg\|html\|css\|js\|txt

ico\|png\|jpg\|jpeg\|gif\|svg\|html\|css\|js\|txtIn conclusion we can say that dependencies go in two places, for the public dependencies, we useresourcesand for the rest we use the root directory by default.My personal use of literate projects with org-mode is for studying and ETL-like processes where there may be data that I need to load fromresources, then output the results in the sameresourcesdirectory. In case of graphs and plots,.pngfiles will be the results, but HTML and JS may also come into play.Default theme and modulesBy default, theresources/themepath of the theme is referenced inconfig/org-theme.configand it will link to a relative path in the project directory.However, there is a second file namedconfig/org-theme-alt.configthat will link to an external and absolute path that we can use instead of the default one.We must set the name of the file in the header of our.orgfiles and runC-c C-cin order to update the configuration.#+SETUPFILE: ../config/org-theme-alt.configThen we can edit the contents of the file to fit our needs. Its default values link to theorg-templaterepository but we can set them to wherever else.Once we don’t need the theme inresources/themewe can remove it from the repository.gitrmresources/theme
gitcommit"removed default theme"That way we don’t copy the contents to thepublicfolder, as we are no longer using it. This can also be useful when dealing with a nested project where we may have trees of org projects and we want them to use the same common theme.Running from a parent projectWe can apply the same idea to the headers of the org file and redirect to an absolute path outside of the.orgfile directory. Then we can runmakefrom a parent repository because the default behaviour ofpublish.elis to act recursively, so all.orgfiles in whatever directory we set,srcby default, will be exported to the parent’s directory respectivepublicanddocsdirectories.In that case, we should also copy the resources path recursively in order to keep the folder structure of the new tree.Code ExamplesShell ExampleShell source blocks don’t tangle as they are normally one liners. This particular line just sets the local Python environment viapyenv, I don’t need avenvfor this demo.We must make sure that:diris set to the parent directory...pyenvlocal3.7.13&&cat.python-version3.7.13SQL ExampleThis is an SQL query for the database specified in theorg-header.configfile, which is the pagila sample database. For changing the sql info it’s always better to override theheader-argsin the current document while using the original configuration as reference.SELECTCONCAT(customer.last_name,', ',customer.first_name)AScustomer,address.phone,film.titleFROMrentalINNERJOINcustomerONrental.customer_id=customer.customer_idINNERJOINaddressONcustomer.address_id=address.address_idINNERJOINinventoryONrental.inventory_id=inventory.inventory_idINNERJOINfilmONinventory.film_id=film.film_idWHERErental.return_dateISNULLANDrental_date<CURRENT_DATEORDERBYtitleLIMIT5;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 FOREVERElisp ExampleElisp 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-11Python ExamplePython 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.To DoTODO Fix the README file in the project root.Problem: Whenever using the README.md file outside of a repository with theresourcesfolder, the image links break.Possible solution: Whenever copying the README.md to root, process it with a Python script so it references the public url address.AdmonitionsSupport 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.