Design Discussion: build and generate

[oscarlevin]

As part of the refactor, I've been thinking about separation of concerns for the basic functionality of the CLI. This is most prevalent with build and generate, although view and deploy might require some attention too.

Right now, when a user runs pretext build, we first run through the build function of cli.py, which

• Does some verification that building can happen
• Reports info/warnings/errors
• Optionally calls project.generate (which will become target.generate)
• Calls project.build (soon target.build)

Then the class methods in project/__init__.py take over. This entails:

• Some verification that building can happen by checking whether the source is reasonable
• Reports info/warnings/errors
• Creates/deletes some directories if they are missing/if user asked for a clean build
• Handles custom xsl
• Calls the build function from build.py (either a single one or one based on the format)

Then the build function of build.py:

• (In the new version) decides what format is being built and then calls the format's build function in build.py.
• Each format function (e.g. html()) then makes the output directory if needed, does some reporting, and then in a working directory context, calls the core.[format-name] function.

The story for generate is almost the same, except the last step also specifies some formats based on the target-format, and re-verifies that anything needs to be done at all (this seems unnecessary).

I don't like having to look in three or four spots to find where each check, message, directory-making occurs. It seems like we should be able to eliminate the build.py and generate.py functions by making them methods of the target class. However, that makes the target class really bulky. I've seem some options for pulling these functions into their own files (inside the project module/directory), the simplest being to just include these in the __init__.py file. Another option would be to do some sort of subclass thing, but I'm not seeing what the objects would be.

What do you think?

[StevenClontz]

Just quickly chiming in to apologize for dropping off the past few days - been working on preparing for MathFest and POSE proposal stuff. My goal is to be back in dev mode by this afternoon's dropin.

[bjones1]

First, way to go for thinking this through, rather than blindly coding away! It's great to sit down and plan out some good, long-term maintainable software architecture.

The short answer: I don't know what the best approach is, but I suspect it will become clear through this refactor. First, putting all the code in a target class/subclass makes a LOT of sense. I think this is the clearest path forward. From there, let's see what we learn. If the build/generate code has lots of similarity (create these directories, perform these checks, etc.), then we can factor that out. If each target's code is fairly different, we can make a set of TargetHtml, TargetLatex, etc. that have target-specific methods for these cases.