Converts course material to naucse.python.cz API
Project description
naucse_render
Helper for converting course material in YAML/Markdown/Jupyter to naucse.python.cz JSON API.
Entrypoints
Get a list of available courses:
naucse_render.get_course_slugs(*, path='.')
Get general course information:
naucse_render.get_course(course_slug, *, path='.', version=None)
Get information about lessons:
naucse_render.get_lessons(lesson_slugs, vars=None, path='.')
Compile a given course into a directory of JSON & HTML files:
def compile(slug=None, *, path='.', destination, edit_info=None)
The path
specifies the local filesystem path to the root of the repository
(i.e. parent directory of courses
, runs
and lessons
).
Installation & CLI Usage
Install the latest released version from PyPI. With an activated virtualenv, do:
(venv)$ pip install naucse_render
For development, you can instead install in editable mode
with dev
dependencies:
(venv)$ pip install -e.[dev]
You can run naucse_render from the command line. To “compile” a course to a directory of JSON metadata and static files:
(venv)$ python -m naucse_render compile _built/
To output metadata for a course or individual lesson(s):
(venv)$ python -m naucse_render get-course
(venv)$ python -m naucse_render get-lessons beginners/install beginners/venv-setup
By default, data is retreived from the current working directory.
Use the --path
option to point naucse_render elsewhere.
You can use --help
for more info.
Tests
To run tests, install this package with development dependencies:
(venv)$ pip install -e.[dev]
then run the tests with pytest
:
(venv)$ python -m pytest
License
The code is licensed under the terms of the MIT license, see LICENSE.MIT file for full text. By contributing code to this repository, you agree to have it licensed under the same license.
Changelog
naucse_render 2.0
-
Update to mistune 3.x & nbconvert 7.x. This changes parsing & formatting for Markdown, syntax highlighting, and Notebooks. In most cases the differences should be superficial.
-
Tested with Python 3.8-3.12
naucse_render 1.10
-
naucse_render compile
now checks for links to missing lessons and non-existentid
s in lessons. It fails if one is found. -
Fixed links after headings
-
API version 0.4
- Each page of a lesson now has a
links
entry with a list of all links found on the page. - Each page of a lesson now has a
ids
entry with a list of allid
attributes found on the page.
- Each page of a lesson now has a
naucse_render 1.9
naucse_render
now works with current releases of Jinja2.
naucse_render 1.8
naucse_render compile
now supports the--all
switch, which compiles all available courses to directories under the destination directory. This is now the default when--slug
is not given and a default course is not found. This change should allow using a common CI config for all repos with course definitions.- Anchors are now automatically added to all headers, making it possible to link to individual sections. (thanks to Jakub Beránek)
naucse_render 1.7
- Added the function
naucse.get_course_slugs()
and the CLI subcommandnaucse_render ls
, which return a list of courses naucse_render can load from the given directory. - Courses may now be specified with a "flat" file like
courses/<course-slug>.yml
, rather than ainfo.yml
file nested in a directory.
naucse_render 1.6
- Courses can now specify
extra_lessons
, a list of lessons thatcompile
will include in its output even if they don't appear in session materials. This is more explicit than relying on links in the course content (which would need to be parsed any time this info is needed, making things slower).
naucse_render 1.5
-
A new subcommand,
compile
, creates a directory with course data and supporting files. -
API version 0.3
- A course may have information about "edit info", specifying where the course's sources can be edited. (This is only set when compiling courses; in other cases, the caller should know where the code lives.)
-
The
slug
is now optional; if not given (or None), the data is loaded fromcourse.yml
(in the givenpath
, by default the current directory) rather than a file inruns/
orcourses/
.
naucse_render 1.4
Compatible with nbconvert
6.0.
naucse_render 1.3
- Lesson directories without data are ignored (https://github.com/pyvec/naucse_render/issues/15)
- API version 0.2
- Subpages now have subtitles
- Non-
index
subpages may optionally have asubtitle
. For example, a lesson named "Installation" might have a OS-specific subpage with the subtitle "Linux". - If the
title
of a non-index
subpage may now be missing in the input. In that case, thesubtitle
must be present, and thetitle
is generated as"{lesson title} – {page subtitle}"
.
- Non-
- Timezone information is passed through
- Mappings read from YAML must have unique keys.
- Subpages may now be linked with relative URLs:
./page
, just like other lessons can be linked with../lesson
or../../category/lesson
. ("Short" linking to subpages of other lessons, like, still doesn't work.)../lesson/page
naucse_render 1.2
- API version 0.1
- Serial "numbers" are now generated for sessions.
- Serials are strings (or None). Usually they are numeric (like
'1'
), and in the source YAML they may be specified as int. But, for example, an appendix could use Roman numerals:i
,ii
,iii
. - When a serial is not given in the source YAML explicitly, it is
auto-generated as the previous serial plus 1 (or from
1
at the start). Serials specified as str (or None) prevent this auto-generation. - For courses with only one session, the serial is not auto-generated.
- Serials are strings (or None). Usually they are numeric (like
naucse_render 1.1
- Make it possible to use data from a YAML file in lesson content
- Make output the same on Windows as on "Unixy" systems
naucse_render 1.0
- Source files are always reported as relative paths
- YAML files are reloaded when they change
- Added integration tests
naucse_render 0.x
0.x should successfully render courses hosted on naucse.python.cz prior to 2019.
The format of the source files grew organically, so there is no attempt here to document it.
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
Built Distribution
File details
Details for the file naucse_render-2.0.tar.gz
.
File metadata
- Download URL: naucse_render-2.0.tar.gz
- Upload date:
- Size: 20.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | a741a0bbf1b2596f2d070a24cf252dfc4e20b73ad4999bf7ae7940461bd57117 |
|
MD5 | cd1248290be10071a09375420f07f888 |
|
BLAKE2b-256 | 76e34c0c22db3b473297ee89cf9ad846f60b6e66f5f2c94933beb49b2162c852 |
File details
Details for the file naucse_render-2.0-py3-none-any.whl
.
File metadata
- Download URL: naucse_render-2.0-py3-none-any.whl
- Upload date:
- Size: 21.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 987abfa4dec337a9e98daac4b547a5be651a5bc77081f971d8435fbb4c6fbd4f |
|
MD5 | 975e42223afba2fda0c113eae9c32c69 |
|
BLAKE2b-256 | 859fcf82b7653394449f58a773dfa79f40a0965cec871479ff05cb531fe9ba0d |