Skip to main content

A package to author, build, and deploy PreTeXt projects.

Project description

PreTeXt-CLI

A package for authoring and building PreTeXt documents.

Documentation and examples for authors/publishers

Most documentation for PreTeXt authors and publishers is available at:

Authors and publishers may also find the examples catalog useful as well:

We have a few notes below (TODO: publish these in the Guide).

Installation

Installing Python

PreTeXt-CLI requires the Python version specified in pyproject.toml.

To check your version, type this into your terminal or command prompt:

python -V

If your version is 2.x, try this instead (and if so, replace all future references to python in these instructions with python3).

python3 -V

If you don't have a compatible Python available, try one of these:

Installing PreTeXt-CLI

Once you've confirmed that you're using a valid version of Python, just run (replacing python with python3 if necessary):

python -m pip install --user pretext

(It's possible you will get an error like error: invalid command 'bdist_wheel' — good news, you can ignore it!)

After installation, try to run:

pretext --help

If that works, great! Otherwise, it likely means that Python packages aren't available on your “PATH”. In that case, replace all pretext commands with python -m pretext instead:

python -m pretext --help

Either way, you're now ready to use the CLI, the --help option will explain how to use all the different subcommands like pretext new and pretext build.

External dependencies

We install as much as we can with the pip install command, but depending on your machine you may require some extra software:

Upgrading PreTeXt-CLI

If you have an existing installation and you want to upgrade to a more recent version, you can run:

python -m pip install --upgrade pretext

Custom XSL

Custom XSL is not encouraged for most authors, but (for example) developers working bleeding-edge XSL from core PreTeXt may want to call XSL different from that which is shipped with a fixed version of the CLI. This may be accomplished by adding an <xsl/> element to your target with a relative (to project.ptx) or absolute path to the desired XSL. (Note: this XSL must only import other XSL files in the same directory or within subdirectories.)

For example:

<target name="html">
  <format>html</format>
  <source>source/main.ptx</source>
  <publication>publication/publication.ptx</publication>
  <output-dir>output/html</output-dir>
  <xsl>../pretext/xsl/pretext-html.xsl</xsl>
</target>

If your custom XSL file needs to import the XSL shipped with the CLI (e.g. pretext-common.xsl), then use a ./core/ prefix in your custom XSL's xsl:import@href as follows:

<xsl:import href="./core/pretext-common.xsl"/>

Similarly, entities.ent may be used:

<!DOCTYPE xsl:stylesheet [
    <!ENTITY % entities SYSTEM "./core/entities.ent">
    %entities;
]>

Note: previously this was achieved with a pretext-href attribute - this is now deprecated and will be removed in a future release.


Using this package as a library/API

We have started documenting how you can use this CLI programmatically in docs/api.md.


Development

Note. The remainder of this documentation is intended only for those interested in contributing to the development of this project. Anyone who simply wishes to use the PreTeXt-CLI can stop reading here.

From the "Clone or Download" button on GitHub, copy the REPO_URL into the below command to clone the project.

git clone [REPO_URL]
cd pretext-cli

Using a valid Python installation

Developers and contributors must install a version of Python that matching the requirements in pyproject.toml.

Installing dependencies

Optional: use pyenv as a virtual environment

The pyenv tool for Linux automates the process of running the correct version of Python when working on this project (even if you have other versions of Python installed on your system).

Run the following, replacing PYTHON_VERSION with your desired version.

pyenv install PYTHON_VERSION

Steps on Windows

In windows, you can either use the bash shell and follow the directions above, or try pyenv-win. In the latter case, make sure to follow all the installation instructions, including the Finish the installation. Then proceed to follow the directions above to install a version of python matching pyproject.toml. Finally, you may then need to manually add that version of python to your path.


The first time you set up your development environment, you should follow these steps:

  1. Follow these instructions to install poetry.

  2. Install dependencies into a virtual environment with this command.

    poetry install
    
  3. Fetch a copy of the core pretext library and bundle templates by running

    poetry run python scripts/fetch_core.py
    

The last command above should also be run when returning to development after some time, since the core commit you develop against might have changed.

Make sure you are in a poetry shell during development mode so that you execute the development version of pretext-cli rather than the system-installed version.

pretext --version # returns system version
poetry shell
pretext --version # returns version being developed

When inside a poetry shell you can navigate to other folders and run pretext commands. Doing so will use the current development environment version of pretext. In newer versions of poetry, the shell command is not avaiable anymore and is a plugin instead. Alternatively, the command poetry env activate will print a line that you can then run to activate the virtual environment:

pretext --version # returns system version
poetry env activate # returns something like `source ./venv/bin/activate`, which you should now run
source .venv/bin/activate
pretext --version # returns version being developed

Updating dependencies

Show instructions To add dependencies for the package, run
poetry add DEPENDENCY-NAME

If someone else has added a dependency:

poetry install

Using a local copy of PreTeXtBook/pretext

See docs/core_development.md.

Formatting code before a commit

All .py files are formatted with the black python formatter and checked by flake8. Proper formatting is enforced by checks in the Continuous Integration framework. Before you commit code, you should make sure it is formatted with black and passes flake8 by running the following commands (on linux or mac) from the root project folder (most likely pretext-cli).

poetry run black .
poetry run flake8

Testing

Sets are contained in tests/. To run all tests:

poetry run pytest

To run a specific test, say test_name inside test_file.py:

poetry run pytest -k name

Tests are automatically run by GitHub Actions when pushing to identify regressions.

Packaging

To check if a successful build is possible:

poetry run python scripts/build_package.py

To publish a new alpha release, first add/commit any changes. Then the following handles bumping versions, publishing to PyPI, and associated Git management.

poetry run python scripts/release_alpha.py

Publishing a stable release is similar:

poetry run python scripts/release_stable.py # patch +0.+0.+1
poetry run python scripts/release_stable.py minor # +0.+1.0
poetry run python scripts/release_stable.py major # +1.0.0

Asset generation

Generating assets is complicated. See docs/asset-generation.md


About

PreTeXt-CLI Team

A note and special thanks

A pretext package unrelated to the PreTeXtBook.org project was released on PyPI several years ago by Alex Willmer. We are grateful for his willingness to transfer this namespace to us.

As such, versions of this project before 1.0 are released on PyPI under the name pretextbook, while versions 1.0 and later are released as pretext.

About PreTeXt

The development of PreTeXt's core is led by Rob Beezer.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pretext-2.22.0.tar.gz (16.6 MB view details)

Uploaded Source

Built Distribution

pretext-2.22.0-py3-none-any.whl (16.6 MB view details)

Uploaded Python 3

File details

Details for the file pretext-2.22.0.tar.gz.

File metadata

  • Download URL: pretext-2.22.0.tar.gz
  • Upload date:
  • Size: 16.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.12.11 Linux/6.8.0-1029-azure

File hashes

Hashes for pretext-2.22.0.tar.gz
Algorithm Hash digest
SHA256 1d74e903cb05d87e31fadde4deb58bc0792ae73173b0887668bbcbbe1038ae58
MD5 f2c47267eeb5405cb9a535b125246b2f
BLAKE2b-256 dade9528f43925fead4e83ece8d6fac7b87ab6d16f91f70007ed862c7c16af1d

See more details on using hashes here.

File details

Details for the file pretext-2.22.0-py3-none-any.whl.

File metadata

  • Download URL: pretext-2.22.0-py3-none-any.whl
  • Upload date:
  • Size: 16.6 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.12.11 Linux/6.8.0-1029-azure

File hashes

Hashes for pretext-2.22.0-py3-none-any.whl
Algorithm Hash digest
SHA256 13fe1f7f4c4bda41f6439b1a7f230260980eae52583c099f234ceb99c0dfee11
MD5 af153f123e96f9506c91a05cfe0b030e
BLAKE2b-256 5b14fa6a1ebc51689df412165b788a292242e2d5f0f2e18d7a2af094adc3187e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page