| Name | pretext JSON |
| Version |
2.8.0
JSON |
| download |
| home_page | https://pretextbook.org |
| Summary | A package to author, build, and deploy PreTeXt projects. |
| upload_time | 2024-10-18 18:18:08 |
| maintainer | None |
| docs_url | None |
| author | Oscar Levin |
| requires_python | <4.0.0,>=3.8.5 |
| license | GPL-3.0-or-later |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PreTeXt-CLI
A package for authoring and building [PreTeXt](https://pretextbook.org) documents.
- GitHub: <https://github.com/PreTeXtBook/pretext-cli/>
## Documentation and examples for authors/publishers
Most documentation for PreTeXt authors and publishers is available at:
- <https://pretextbook.org/doc/guide/html/>
Authors and publishers may also find the examples catalog useful as well:
- <https://pretextbook.org/examples.html>
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:
- https://www.python.org/downloads/
- Windows warning: Be sure to select the option adding Python to your Path.
- https://github.com/pyenv/pyenv#installation (Mac/Linux)
- https://github.com/pyenv-win/pyenv-win#installation (Windows)
#### 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:
- [TeXLive](https://www.tug.org/texlive/)
- [pdftoppm/Ghostscript](https://github.com/abarker/pdfCropMargins/blob/master/doc/installing_pdftoppm_and_ghostscript.rst)
#### 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._
---
## 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.
```bash
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
<details>
<summary><b>Optional</b>: use pyenv as a virtual environment</summary>
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).
- https://github.com/pyenv/pyenv#installation
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](https://github.com/pyenv-win/pyenv-win#installation). 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.
</details>
<br/>
The first time you set up your development environment, you should follow these steps:
1. Follow these instructions to install `poetry`.
- https://python-poetry.org/docs/#installation
- Note 2022/06/21: you may ignore "This installer is deprecated". See
[python-poetry/poetry/issues/4128](https://github.com/python-poetry/poetry/issues/4128)
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 navegate to other folders and run pretext commands. Doing so will use the current development environment version of pretext.
### Updating dependencies
<details>
<summary>Show instructions</summary>
To add dependencies for the package, run
```
poetry add DEPENDENCY-NAME
```
If someone else has added a dependency:
```
poetry install
```
</details>
### Using a local copy of `PreTeXtBook/pretext`
See [docs/core_development.md](docs/core_development.md).
### Formatting code before a commit
All `.py` files are formatted with the [black](https://black.readthedocs.io/en/stable/)
python formatter and checked by [flake8](https://flake8.pycqa.org/en/latest/).
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
```
---
## About
### PreTeXt-CLI Team
- [Oscar Levin](https://math.oscarlevin.com/) is co-creator and lead developer of PreTeXt-CLI.
- [Steven Clontz](https://clontz.org/) is co-creator and a regular contributor of PreTeXt-CLI.
- Development of PreTeXt-CLI would not be possible without the frequent
[contributions](https://github.com/PreTeXtBook/pretext-cli/graphs/contributors) of the
wider [PreTeXt-Runestone Open Source Ecosystem](https://prose.runestone.academy).
### 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](https://github.com/PreTeXtBook/pretext)
is led by [Rob Beezer](http://buzzard.ups.edu/).
Raw data
{
"_id": null,
"home_page": "https://pretextbook.org",
"name": "pretext",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.5",
"maintainer_email": null,
"keywords": null,
"author": "Oscar Levin",
"author_email": "oscar.levin@unco.edu",
"download_url": "https://files.pythonhosted.org/packages/e7/a8/8b5a66be95adc906b16fc372da5bdb0d8b7107ae133087318dd573426c34/pretext-2.8.0.tar.gz",
"platform": null,
"description": "# PreTeXt-CLI\n\nA package for authoring and building [PreTeXt](https://pretextbook.org) documents.\n\n- GitHub: <https://github.com/PreTeXtBook/pretext-cli/>\n\n## Documentation and examples for authors/publishers\n\nMost documentation for PreTeXt authors and publishers is available at:\n\n- <https://pretextbook.org/doc/guide/html/>\n\nAuthors and publishers may also find the examples catalog useful as well:\n\n- <https://pretextbook.org/examples.html>\n\nWe have a few notes below (TODO: publish these in the Guide).\n\n### Installation\n\n#### Installing Python\n\nPreTeXt-CLI requires the Python version specified in `pyproject.toml`.\n\nTo check your version, type this into your terminal or command prompt:\n\n```\npython -V\n```\n\nIf your version is 2.x, try this instead\n(and if so, replace all future references to `python`\nin these instructions with `python3`).\n\n```\npython3 -V\n```\n\nIf you don't have a compatible Python available, try one of these:\n\n- https://www.python.org/downloads/\n - Windows warning: Be sure to select the option adding Python to your Path.\n- https://github.com/pyenv/pyenv#installation (Mac/Linux)\n- https://github.com/pyenv-win/pyenv-win#installation (Windows)\n\n#### Installing PreTeXt-CLI\n\nOnce you've confirmed that you're using a valid version of Python, just\nrun (replacing `python` with `python3` if necessary):\n\n```\npython -m pip install --user pretext\n```\n\n(It's possible you will get an error like\n`error: invalid command 'bdist_wheel'`\n\u2014 good news, you can ignore it!)\n\nAfter installation, try to run:\n\n```\npretext --help\n```\n\nIf that works, great! Otherwise, it likely means that Python packages\naren't available on your \u201cPATH\u201d. In that case, replace all `pretext`\ncommands with `python -m pretext` instead:\n\n```\npython -m pretext --help\n```\n\nEither way, you're now ready to use the CLI, the `--help` option will explain how to use all the different\nsubcommands like `pretext new` and `pretext build`.\n\n#### External dependencies\n\nWe install as much as we can with the `pip install` command, but depending on your machine\nyou may require some extra software:\n\n- [TeXLive](https://www.tug.org/texlive/)\n- [pdftoppm/Ghostscript](https://github.com/abarker/pdfCropMargins/blob/master/doc/installing_pdftoppm_and_ghostscript.rst)\n\n#### Upgrading PreTeXt-CLI\n\nIf you have an existing installation and you want to upgrade to a more recent version, you can run:\n\n```\npython -m pip install --upgrade pretext\n```\n\n#### Custom XSL\n\nCustom XSL is not encouraged for most authors, but (for example) developers working\nbleeding-edge XSL from core PreTeXt may want to call XSL different from that\nwhich is shipped with a fixed version of the CLI. This may be accomplished by\nadding an `<xsl/>` element to your target with a relative (to `project.ptx`) or\nabsolute path to the desired XSL. _(Note: this XSL must only import\nother XSL files in the same directory or within subdirectories.)_\n\nFor example:\n\n```\n<target name=\"html\">\n <format>html</format>\n <source>source/main.ptx</source>\n <publication>publication/publication.ptx</publication>\n <output-dir>output/html</output-dir>\n <xsl>../pretext/xsl/pretext-html.xsl</xsl>\n</target>\n```\n\nIf your custom XSL file needs to import the XSL\nshipped with the CLI (e.g. `pretext-common.xsl`), then use a `./core/`\nprefix in your custom XSL's `xsl:import@href` as follows:\n\n```\n<xsl:import href=\"./core/pretext-common.xsl\"/>\n```\n\nSimilarly, `entities.ent` may be used:\n\n```\n<!DOCTYPE xsl:stylesheet [\n <!ENTITY % entities SYSTEM \"./core/entities.ent\">\n %entities;\n]>\n```\n\n_Note: previously this was achieved with a `pretext-href` attribute - this is now deprecated and will be removed in a future release._\n\n---\n\n## Development\n\n**Note.** The remainder of this documentation is intended only for those interested\nin contributing to the development of this project. Anyone who simply wishes to\n_use_ the PreTeXt-CLI can stop reading here.\n\nFrom the \"Clone or Download\" button on GitHub, copy the `REPO_URL` into the below\ncommand to clone the project.\n\n```bash\ngit clone [REPO_URL]\ncd pretext-cli\n```\n\n### Using a valid Python installation\n\nDevelopers and contributors must install a\nversion of Python that matching the requirements in `pyproject.toml`.\n\n\n### Installing dependencies\n<details>\n<summary><b>Optional</b>: use pyenv as a virtual environment</summary>\n\nThe `pyenv` tool for Linux automates the process of running the correct\nversion of Python when working on this project (even if you have\nother versions of Python installed on your system).\n\n- https://github.com/pyenv/pyenv#installation\n\nRun the following, replacing `PYTHON_VERSION` with your desired version.\n\n```\npyenv install PYTHON_VERSION\n```\n#### Steps on Windows\n\nIn windows, you can either use the bash shell and follow the directions above,\nor try [pyenv-win](https://github.com/pyenv-win/pyenv-win#installation). In\nthe latter case, make sure to follow all the installation instructions, including\nthe **Finish the installation**. Then proceed to follow the directions above to\ninstall a version of python matching `pyproject.toml`. Finally, you may then need\nto manually add that version of python to your path.\n\n</details>\n\n<br/>\n\nThe first time you set up your development environment, you should follow these steps:\n\n1. Follow these instructions to install `poetry`.\n\n - https://python-poetry.org/docs/#installation\n - Note 2022/06/21: you may ignore \"This installer is deprecated\". See\n [python-poetry/poetry/issues/4128](https://github.com/python-poetry/poetry/issues/4128)\n\n2. Install dependencies into a virtual environment with this command.\n\n ```\n poetry install\n ```\n\n3. Fetch a copy of the core pretext library and bundle templates by running\n\n ```\n poetry run python scripts/fetch_core.py\n ```\n\nThe last command above should also be run when returning to development after some time, since the core commit you develop against might have changed.\n\n\nMake sure you are in a `poetry shell` during development mode so that you\nexecute the development version of `pretext-cli` rather than the system-installed\nversion.\n\n```\npretext --version # returns system version\npoetry shell\npretext --version # returns version being developed\n```\n\nWhen inside a `poetry shell` you can navegate to other folders and run pretext commands. Doing so will use the current development environment version of pretext.\n\n\n### Updating dependencies\n<details>\n<summary>Show instructions</summary>\nTo add dependencies for the package, run\n\n```\npoetry add DEPENDENCY-NAME\n```\n\nIf someone else has added a dependency:\n\n```\npoetry install\n```\n</details>\n\n\n### Using a local copy of `PreTeXtBook/pretext`\n\nSee [docs/core_development.md](docs/core_development.md).\n\n\n\n### Formatting code before a commit\n\nAll `.py` files are formatted with the [black](https://black.readthedocs.io/en/stable/)\npython formatter and checked by [flake8](https://flake8.pycqa.org/en/latest/).\nProper formatting is enforced by checks in the Continuous Integration framework.\nBefore you commit code, you should make sure it is formatted with `black` and\npasses `flake8` by running the following commands (on linux or mac)\nfrom the _root_ project folder (most likely `pretext-cli`).\n\n```\npoetry run black .\npoetry run flake8\n```\n\n### Testing\n\nSets are contained in `tests/`. To run all tests:\n\n```\npoetry run pytest\n```\n\nTo run a specific test, say `test_name` inside `test_file.py`:\n\n```\npoetry run pytest -k name\n```\n\nTests are automatically run by GitHub Actions when pushing to identify\nregressions.\n\n### Packaging\n\nTo check if a successful build is possible:\n\n```\npoetry run python scripts/build_package.py\n```\n\nTo publish a new alpha release, first add/commit any changes. Then\nthe following handles bumping versions, publishing to PyPI,\nand associated Git management.\n\n```\npoetry run python scripts/release_alpha.py\n```\n\nPublishing a stable release is similar:\n\n```\npoetry run python scripts/release_stable.py # patch +0.+0.+1\npoetry run python scripts/release_stable.py minor # +0.+1.0\npoetry run python scripts/release_stable.py major # +1.0.0\n```\n\n---\n\n## About\n\n### PreTeXt-CLI Team\n\n- [Oscar Levin](https://math.oscarlevin.com/) is co-creator and lead developer of PreTeXt-CLI.\n- [Steven Clontz](https://clontz.org/) is co-creator and a regular contributor of PreTeXt-CLI.\n- Development of PreTeXt-CLI would not be possible without the frequent\n [contributions](https://github.com/PreTeXtBook/pretext-cli/graphs/contributors) of the\n wider [PreTeXt-Runestone Open Source Ecosystem](https://prose.runestone.academy).\n\n### A note and special thanks\n\nA `pretext` package unrelated to the PreTeXtBook.org project was released on PyPI\nseveral years ago by Alex Willmer. We are grateful for his willingness to transfer\nthis namespace to us.\n\nAs such, versions of this project before 1.0 are released on PyPI under the\nname `pretextbook`, while versions 1.0 and later are released as `pretext`.\n\n### About PreTeXt\n\nThe development of [PreTeXt's core](https://github.com/PreTeXtBook/pretext)\nis led by [Rob Beezer](http://buzzard.ups.edu/).\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A package to author, build, and deploy PreTeXt projects.",
"version": "2.8.0",
"project_urls": {
"Homepage": "https://pretextbook.org",
"Repository": "https://github.com/PreTeXtBook/pretext-cli"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4d93152696ba555fe5dfd5ed0ac1d072a0f59396f4c8c824a4b86d68506f54d4",
"md5": "2dcb895c187e4e8142e6cfd8b502127d",
"sha256": "3e0fbb82deae0353cda27d884ee0f76ef85412aaf6259599fe1fb49d87114723"
},
"downloads": -1,
"filename": "pretext-2.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2dcb895c187e4e8142e6cfd8b502127d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.5",
"size": 1646341,
"upload_time": "2024-10-18T18:18:06",
"upload_time_iso_8601": "2024-10-18T18:18:06.456380Z",
"url": "https://files.pythonhosted.org/packages/4d/93/152696ba555fe5dfd5ed0ac1d072a0f59396f4c8c824a4b86d68506f54d4/pretext-2.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7a88b5a66be95adc906b16fc372da5bdb0d8b7107ae133087318dd573426c34",
"md5": "fab0789843bfc93860421426a2da3599",
"sha256": "e7ad11a74feb0077323fe2eddae3f710b57032985f811713fb03a18672302a9a"
},
"downloads": -1,
"filename": "pretext-2.8.0.tar.gz",
"has_sig": false,
"md5_digest": "fab0789843bfc93860421426a2da3599",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.5",
"size": 1640473,
"upload_time": "2024-10-18T18:18:08",
"upload_time_iso_8601": "2024-10-18T18:18:08.590477Z",
"url": "https://files.pythonhosted.org/packages/e7/a8/8b5a66be95adc906b16fc372da5bdb0d8b7107ae133087318dd573426c34/pretext-2.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-18 18:18:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PreTeXtBook",
"github_project": "pretext-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pretext"
}
