Best-practice project architecture for creating a LaTeX3 package / class

Question

I would like to take my .cls file and refactor it into a locally used package. Specifically I would like to:

1. Divide it into multiple files for easier readability (separation of concerns).
2. Have it usable in a document as \documentclass{mypackage} (not a package, via).
3. Have it easy to compile in one step so it can be developed in parallel when editing a document.

I am looking at an example well-defined project such as siunitx for a reference implementation and notice a few things.

• .dtx files for merging documentation with code.
• build.lua for it seems like building the package with a version.
• install.sh for travisci (not necessary for my case).
• single .ins file, not sure what this is for ("installation routine").

According to this wiki, there are ~5 steps to creating a package.

1. Unpack files
2. Create docs
3. Install files
4. Update index (of the package database on your computer)
5. Update font maps if used any fonts

I would like to somehow create a workflow that streamlines this process into a single cli command so whenever the package changes, I can just run that and refresh my document and it works.

In other programming environments such as Node.js you can simply create a folder with a specific configuration file, then symlink it using the node package manager's cli. Then you can just import the package in your project, and because it is dynamically compiled no compiling is necessary.

Wondering what the recommended approach is for this in the community. So in the end I would have a package structure along the lines of:

src
src/a.tex
src/b.tex
src/c.tex
index.tex # loads a, b, c perhaps maybe via `\include`
build.sh
install.sh
package.config.something?

Not sure if that's how community best practices would do it, hoping to learn a good approach.

Some other reference implementations are:

• https://github.com/josephwright/siunitx (build.lua)
• https://github.com/josephwright/beamer (build.lua, this is probably the closest to what I would like to do)
• https://github.com/raphink/moderntimeline (ruby for compiling)
• https://github.com/circuitikz/circuitikz (makefile?)
• https://github.com/alecjacobson/coloremoji.sty (texhash coloremoji.sty)
• https://github.com/wilbowma/mttex (this uses ln -s mttex/*.sty . seemlingly to dynamically compile, that seems neat :))
• https://github.com/drayside/graphviz.sty (makefile for .sty?)
• https://github.com/battlesnake/neural (.sty)
• https://github.com/astoeckel/smart-thesis (documentclass, uses makefile)

So it doesn't look like there is really a standard. The answer on How do I create a LaTeX package? is more about latex programming and package publishing then a workflow on structuring and developing a package. The documentation on this wiki says you need to create a .sty file, but not all the above linked packages have one so it doesn't seem necessary. This was also helpful: Where do I place my own .sty or .cls files, to make them available to all my .tex files?

What I have tried so far is essentially this MWE:

CWD := $(shell pwd)
# DIR := $(shell kpsewhich -var-value=TEXMFHOME)/tex/latex/$(NAME)
DIR := $(HOME)/texmf/tex/latex

#
# Install.
#
# NAME=myclass make install
#

install:
  @mkdir -p $(DIR)
  @ln -sf $(CWD)/index.cls $(DIR)/$(NAME).cls
.PHONY: install

#
# Test.
#

test:
  @pdflatex -shell-escape ./test.tex
  @rm ./test.aux ./test.log ./test.out
.PHONY: test

With index.cls file:

\NeedsTeXFormat{LaTeX2e}[2018/03/16 My Class]
\ProvidesClass{myclass}
\LoadClass{article}
\RequirePackage{expl3}
\ExplSyntaxOn

And test.tex file:

\documentclass{myclass}
\begin{document}
Hello world.
\end{document}

Would like to know if this is a decent configuration or if not, what the best-practice.

Answer 1

This perhaps is not an answer but rather an extended comment. You don't say so but I assume that your intended packages are not meant to be used stand-alone.

I was the original creator of the memoir class which is essentially a concatenation of the book, report and article classes together with many packages (most of which I had previously written).

There was some interaction between the individual packages which when coded within the class I was able to handle efficiently; for instance, in some cases code was repeated in two or more packages which could be provided as "common" within the class.

When developing the memoir code I used the regular "LaTeX Package Documentation Tools" (chapter 14 in the "LaTeX Companion") methods. Within the memoir.dtx file which provides the commented class code the "packages" are treated as separate sections (no need to call upon external code). To change a package just edit the appropriate section (in the class file).

In essence I am suggesting that instead of distributing your code across multiple files, keep it all in one file but in distinct areas. Then, for upgrading there is only one file you need to deal with instead of possibly many.