diff --git a/book/_toc.yml b/book/_toc.yml index af02515..0219d36 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -30,6 +30,10 @@ parts: - file: workflows/merge_request.md - file: installation-and-setup/collab - file: installation-and-setup/versioning + sections: + - file: installation-and-setup/versions_URLs + - file: installation-and-setup/versioning_changelog + - file: installation-and-setup/publisher - file: installation-and-setup/copyright.md sections: - file: installation-and-setup/copyright/considerations @@ -62,6 +66,7 @@ parts: - file: external/Nested-Books/README.md title: (Deprecated) Share content between books using submodules - file: features/update_env + - file: features/versioning - file: features/sphinx_extensions.md sections: - file: external/Download-Link-Replacer/README.md diff --git a/book/credits.md b/book/credits.md index 7a22754..64caec1 100644 --- a/book/credits.md +++ b/book/credits.md @@ -60,6 +60,7 @@ The following pages contain content written by others, part of has been reused a - Pages {ref}`copyright` and {ref}`copyright_considerations` include text from {cite:t}`tud_cip_24` that is used in the copyright checklist items. Original content licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY. - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024. +- page [](./features/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches deleted file mode 160000 index 370986c..0000000 --- a/book/external/JupyterBook-Patches +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 370986ca6fd124a0243311647a20c1aeb372bd3a diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches new file mode 100644 index 0000000..d5efad9 --- /dev/null +++ b/book/external/JupyterBook-Patches @@ -0,0 +1 @@ +3a1ed3738693931fb735810cbc7a9a5734e85788 \ No newline at end of file diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 94d5835..a8e57da 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 94d583570178ede097f8216b2aa06996d6e4b9ee +Subproject commit a8e57da25302d47806ad1fe4288950c438562199 diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index 7663b1f..077ba23 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit 7663b1f326e11617a8a35aec7cda0f3d67135551 +Subproject commit 077ba23fa29ef1f0dd454f2ebf93c107923d1068 diff --git a/book/features/figures/toolbar.png b/book/features/figures/toolbar.png new file mode 100644 index 0000000..1960d9c Binary files /dev/null and b/book/features/figures/toolbar.png differ diff --git a/book/features/local_server.md b/book/features/local_server.md index cc7760c..fcdbbc1 100644 --- a/book/features/local_server.md +++ b/book/features/local_server.md @@ -28,6 +28,7 @@ Remember that the browser is serving static files provided by the local server a You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. ``` +(teachbooks-serve)= ## TeachBooks Server: `teachbooks serve` If you have the TeachBooks Python package installed (`pip install teachbooks`), starting a server is as simple as: @@ -38,6 +39,51 @@ teachbooks serve See the {ref}`TeachBooks Package page ` for additional guidance on using the CLI tool. + +By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve: + +```bash +teachbooks serve path unconventional_book_dir/_build/html +``` + +```{tip} +Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated. + +You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. +``` + +To stop the server, simply run + +```bash +teachbooks serve stop +``` + +The CLI tool is set up to make the book edit and check workflow as easy as possible locally: +- you can rebuild the book without restarting the server. +- it reuses an existing server if already running. +- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output. +- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file). + +### Installation of TeachBooks + +The TeachBooks package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows: + +``` +pip install teachbooks +``` + +The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly: + +```bash +pip install --upgrade teachbooks +``` + +We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow `. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice. + +The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. + +The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. + ## Live Server: a VS Code Extension A local server is easy to initialize directly in VS Code using the Live Server extension. Once installed, it can be activated with a "Go Live" button in the bottom right corner of VS Code. The extension will automatically serve index.html, so depending on your book build settings you may need to navigate to the correct directory/file manually using the URL address in the browser. diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index e182063..2561e70 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -1,68 +1,13 @@ (teachbooks-package)= -# Pre- and postprocessing book +# Draft-Release Workflow ```{admonition} User types :class: tip -This page is useful for all users to understand how the book building process works and can be influenced, although the implementation is likely going to be carried out by User Types 3, 4 or 5. +This page is useful for user type 3-5. ``` {bdg-secondary}`Python Package: teachbooks` -The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. - -The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. - -## Primary Features - -Key features (described in the sections below) include: -- pre- and post-processing steps for the Jupyter Book package -- Draft-Release Workflow (`teachbooks build --release book`) -- Start and stop a local server to check your book (`teachbooks serve`) - -This list will be updated periodically as features are added. Check the [Release Notes](https://github.com/TeachBooks/TeachBooks/releases) in the GitHub repository for the most up-to-date information. - -## Installation - -The package is currently only [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows: - -``` -pip install teachbooks -``` - -The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly: - -```bash -pip install --upgrade teachbooks -``` - -We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow `. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice. - -## Contribute - -This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). The `README.md` of the repository describes how you can contribute---don't hesitate to make an issue if you would like to request new features! - -## Description of Features - -(teachbooks-pre-post)= -### Jupyter Book Pre- and Post-Processing - -Using the teachbooks CLI in the book building process generally invokes Jupyter Book. Many of the features in this package are then invoked in the stages before and after this command. The process generally includes the following steps: - -1. Edit source code and prepare to build a book -2. Execute `teachbooks [OPTIONS] COMMAND [ARGS]` -3. Pre-processing step: carried out by `teachbooks` -4. Build step: book is built using `jupyter book [OPTIONS] COMMAND [ARGS]` -5. Post-processing step: carried out by `teachbooks` - -Additional options like those used in jupyterbook (`--all` for example) can be used with `teachbooks` in an identical usage as with the `jupyter-book` command. - -```{note} -The pre- and post-processing steps have not yet bet formally defined; they only exist implicitly in the source code for the `build` CLI command. If you are interested in suggesting a feature or contributing to the package, please visit the [GitHub repository](https://github.com/teachbooks/teachbooks) and take a look at the Discussions and Issues. For example, [this one](https://github.com/orgs/TeachBooks/discussions/28). -``` - -(teachbooks-draft-release)= -### Draft-Release Workflow - Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow `, which builds our TeachBooks). ```{admonition} Why is this useful? @@ -107,38 +52,22 @@ Note that `teachbooks build book` would build a book without stripping the tagge TeachBooks: running build with strategy 'draft' ``` -(teachbooks-serve)= -### Local Python server +## Installation -```{tip} -Visit the {ref}`Local Server page ` for an explanation of why you need a local server. +The package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows: + +``` +pip install teachbooks ``` -The TeachBooks Python package includes a command line interface (CLI) that can be used to start a local server: +The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly: ```bash -teachbooks serve -``` -By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve: - -```bash -teachbooks serve path unconventional_book_dir/_build/html +pip install --upgrade teachbooks ``` -```{tip} -Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated. +We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow `. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice. -You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. -``` +The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. -To stop the server, simply run - -```bash -teachbooks serve stop -``` - -The CLI tool is set up to make the book edit and check workflow as easy as possible locally: -- you can rebuild the book without restarting the server. -- it reuses an existing server if already running. -- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output. -- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file). \ No newline at end of file +The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. \ No newline at end of file diff --git a/book/features/versioning.md b/book/features/versioning.md new file mode 100644 index 0000000..c769c82 --- /dev/null +++ b/book/features/versioning.md @@ -0,0 +1,38 @@ +# TeachBooks Versioning + +> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.` + +Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors: + +1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. +2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. + +We have come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`): + +`````{tab-set} +````{tab-item} academic_year.additions.errata +1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version. +4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented. +5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. + +An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions. +```` +````{tab-item} major.errata +1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0 +2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. +3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version. +5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented. +6. Precedence refers to how versions are compared to each other when ordered. + 1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order. + 2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1. +7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself. +```` +````` + +Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases! \ No newline at end of file diff --git a/book/features/widgets.ipynb b/book/features/widgets.ipynb index 2d441bb..cf1f593 100644 --- a/book/features/widgets.ipynb +++ b/book/features/widgets.ipynb @@ -40,7 +40,24 @@ "```python\n", "input_slider = widgets.FloatSlider(value=0, min=0, max=10, step=1, description='Input variable:') # Defines a widget, more options than just FloatSlider\n", "widgets.interact(update_plot, input_variable_from_widget = input_slider);\n", - "```\n" + "```\n", + "\n", + "Finally, When using `%matplotlib widget`, there's the following toolbar:\n", + "\n", + "![](./figures/toolbar.png)\n", + "\n", + "Which only shows up when you hoover above. If you want to disable the toolbar you can use:\n", + "```python\n", + "fig = plt.gcf()\n", + "fig.canvas.toolbar_visible = False\n", + "```\n", + "\n", + "If you want it to be visible even if you don't hoover above it, use:\n", + "\n", + "```python\n", + "fig = plt.gcf()\n", + "fig.canvas.toolbar_visible = True\n", + "```" ] }, { diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index de7f906..9db1239 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -15,6 +15,7 @@ Furthermore, establish a clear editing and review process. For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {fa}`fa-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised. +(draft_book)= ## Define draft version of book If there's many people working on different parts of the book and material is staged for publication to students, we recommend using at least two separate branches, one which is released to students, the other one for development. Using the [](../external/deploy-book-workflow/README.md), it's very easy to share multiple versions of your book on the same root-URL. diff --git a/book/installation-and-setup/figures/tags_github.png b/book/installation-and-setup/figures/tags_github.png new file mode 100644 index 0000000..0092a24 Binary files /dev/null and b/book/installation-and-setup/figures/tags_github.png differ diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md index b9559d2..4434739 100644 --- a/book/installation-and-setup/git.md +++ b/book/installation-and-setup/git.md @@ -5,23 +5,39 @@ This page is useful for user type 3-5. ``` -You'll need to interact with Git to collaborate on TeachBooks. You've been introduced to it in the [exercises in the template](../intro/template.md) and you'll be guided through all of the steps in detail in [](../workflows/collaboration.md), but what is this thing? +You will need to interact with Git to collaborate on a TeachBook, even if you are working by yourself! You've been introduced to it in the [exercises in the template](../intro/template.md) and you'll be guided through all of the steps in detail in [](../workflows/collaboration.md), but what is this "thing" that sounds suspiciously like something only a computer scientist would want to use? + +```{tip} + +Perhaps you are wondering: _Why a new tool? Why not something I already know like Microsoft Word and Track Changes? Or something like OneDrive or Dropbox?_ + +- Git is 100% free, and online tools like GitHub extend this functionality for free. +- Git is explicitly designed for text-based files, which is how the content of a TeachBook is written. +- You will never have to work with many versions of the same file again (e.g., no more "My_Doc_FINAL_v3_RL_again_final.docx"!). +- Online tools like GitHub provide an easy way to backup your work _and_ to allow others to see it. +- Online tools like GitHub also provide a great way to collaborate, for example: discuss changes to your content, allow others to make suggestions for improvement and fix software issues. +- Online tools like Zenodo allow for long term (decades!) preservation of your work and the ability to update your work with version numbers, dates and DOI's. + +We don't deny that it can take some time to get familiar to the new terminology and workflow associated with Git, and even longer to feel comfortable with it. However, we _promise_ that if you dedicate a little bit of time to learning about this tool it will make your new life creating online interactive textbooks much easier and more enjoyable. + +``` ## What is Git? -Git is a version control system (VCS), used by a wide variety of engineers and software developers to work on projects in parallel together. It provides multiple benefits such as tracking changes to files, working side by side with other people, and the ability to rollback to previous versions of files without losing track of newer changes. It is a free and open sources software. - +Git is a version control system (VCS), used by a wide variety of engineers and software developers to work on projects in parallel together. It provides multiple benefits such as tracking changes to files, working side by side with other people, and the ability to rollback to previous versions of files without losing track of newer changes. It is a free and open sources software. It is especially useful for TeachBooks because it is explicitly designed to handle text-based files, which are essential for writing the contents of a book. ### What is GitHub? -GitHub is the same service as GitLab, but it's part of a commercial company (Microsoft). It's the most well-known cloud-based Git provider and provides a lot of functionalities for free for education. It also allows you to host websites on `github.io` eliminating the need for your own / TU Delft webserver, although you don't have full servercontrol. +GitHub is a software service that is accessed primarily via a web browser at `github.com`; since 2018 it is owned by Microsoft. It is the most well-known cloud-based Git provider and provides a lot of functionalities for free for open source projects, and even more free services for education. Via a service called GitHub Pages, it also allows you to host websites on `github.io` for free eliminating the need for your own web server (however, you don't have full control over the server setup and operation). -For first users, we advise you to use GitHub. +For new TeachBooks users, we advise you to use GitHub. In addition, we recommend you start by making all of your respositories public (unless they contain sensitive information); this will make it easier for others to collaborate with and help you if you get stuck! ### What is GitLab? -GitLab is a cloud-based version control system built around Git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com. +GitLab is a cloud-based version control system built around Git; it is a competitor of GitHub, as the two provide many of the same services (but note the names of things can differ, for example, a _Pull Request_ on GitHub is a _Merge Request_ on GitLab). GitLab provides a lot more features to extent Git such as Issues, Merge Requests, CI/CD pipelines, etc. +For TU Delft employees: TU Delft has a license to use GitLab on our own local webservers---this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an undesirable (physical) location. This is also why we have our “own” GitLab located at `gitlab.tudelft.nl`, rather than the “normal” GitLab at `gitlab.com`. One reason we don't recommend beginning TeachBooks users at TU Delft start with the TU Delft GitLab is that it does not have an automatic website hosting service set up; instead, it must be manually set up on a TU Delft web server (this is straightforward to do, for example, by BSc students from the Computer Science faculty). GitHub Pages provides this service for free and has proven to be very reliable, so start there! ### Additional lessons -Software carpentry offers git-lessons if you'd like to learn more than just it's specific use for TeachBooks. The lessons are available [online](https://swcarpentry.github.io/git-novice/) and TU Delft offers these as part of a [Software Carpentry workshop](https://www.tudelft.nl/library/research-data-management/r/training-evenementen/training-voor-onderzoekers/software-carpentry-workshops) \ No newline at end of file + +Software carpentry offers git-lessons if you'd like to learn more than just it's specific use for TeachBooks. The lessons are available [online](https://swcarpentry.github.io/git-novice/) and TU Delft offers these as part of a [Software Carpentry workshop](https://www.tudelft.nl/library/research-data-management/r/training-evenementen/training-voor-onderzoekers/software-carpentry-workshops) diff --git a/book/installation-and-setup/publisher.md b/book/installation-and-setup/publisher.md new file mode 100644 index 0000000..236715f --- /dev/null +++ b/book/installation-and-setup/publisher.md @@ -0,0 +1,6 @@ + +# Publishing your book with a publisher +You can choose to publish your online book with a publisher. This could increase findability of your book, but may have consequenses on the ease of editing, choice of platforms, versioning restrictions, and copyright and licensing considerations. + +For TU Delft employees, you can decide to publish via TU Delft OPEN interactive textbooks. Publishing will give you a copyright check, ISBN or DOI number, and registration in several shared databases but limits the amount of changes you can make to your book: for substantial changes a new published version is needed with an updated copyright checks. Small changes like typos can always be made, which are processed in the published version every hour. +In case of editing a book for a course during that actual course and/or your book has limited value outside your course's content, we advise you only to publish an archived version of your book whenever the academic year is over. diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index 5899a4d..e265115 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.md @@ -5,27 +5,29 @@ This page is useful for user type 4-5. ``` -Online books can be easily updated, however, this might confuse readers. Therefore, it's good practice to be aware of this and, where needed, provide explicit version to the readers. It's recommended to do this in multiple ways, which can be combined: -- Publish versions on separate (fixed) URLs -- Use some sort of semantic versioning with tags -- Keep both source code as (export of) websites of archived versions -- Publishing your book more officially +Online books can be easily updated, however, this might confuse readers. Therefore, it's good practice to be aware of this and, where needed, provide an explicit version to the readers. -## Publish version on separate (fixed) URLs -When making books for education, typically your book can change substantially for consequential academic years. Using the [](../external/deploy-book-workflow/README.md), you can release the different version of your book all under the same root URL. If you name each students' version of each year to the ``, the students URL includes that academic year too. It is recommended to yearly update the current academic year branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings). This ensures that students are redirected to a consistent URL, even when new versions of the book are added later. Eventually, you can add old branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state. +For example when making taylor-made books for specific academic years, you want students to be able to find their own book (even after the academic year is over). For students which take the course twice, you might want to provide some sort of changelog of what has been changed. -If you plan on maintaining only one public version, it is advisable to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy`. This ensures that the primary branch is copied to the root, making the URL more compact. +Another example could be a book in which you add content and solutions during the course or you're fixing mistakes which may have misinformed the reader. If this is not directly visible in the table of contents, students might not be aware of these changes. Again, a changelog could be useful to inform the reader about the change. Furthermore, a smart versioning system might tell the reader something about the impact of the addition differentiating errata and additions. -Don't forget to explain how you organize these URLs in your README and eventually in the book itself too with a sentence like this: +You could also think of your published book which is referenced by other people. Don't be afraid, git makes it very easy to make this possible. Git allows you to go back in the git history. To make this as easy as possible for readers, you can assign versions using TeachBooks versioning instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions. -> This is the 2024-2025-version of this book. Go to `` to view the most recent version of this book, or adapt the year in `/` to the year when you took the course. +Maybe this all sounds confusing and difficult. No worries! A use-case could be a book which progresses in time, but in which you don't want to deal with the additional hassle of versioning. Your book could be perfectly fine without any measures on this topic! -If you've many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store +If you are part of the previous group, but at some point decide to make a new version of the book while keeping the old one, you could do so without dealing with version numbers and changelogs. Just publish both versions online. -## Semantic versioning +Finally, you might consider publishing your book at an online publisher. This could increase findability of your book and you might benefit from the brand of the publisher, but it may have flexibility, copyright and licensing consequences. -## Publishing your book with publisher -You can choose to publish your online book with a publisher. This could increase findability of your book, but may have versioning, copyright and licensing consequences +So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below in order of increasingly effort and impact. You can combine use-cases to your liking: -For TU Delft employees, you can decide to publish via TU Delft OPEN interactive textbooks. Publishing will give you a copyright check, ISBN or DOI number, and registration in several shared databases but limits the amount of changes you can make to your book: for substantial changes a new published version is needed with an updated copyright checks. Small changes like typos can always be made, which are processed in the published version every hour. -In case of editing a book for a course during that actual course and/or your book has limited value outside your course's content, we advise you only to publish an archived version of your book whenever the academic year is over. \ No newline at end of file +| Use-case | [Publish versions on separate URLs](./versions_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Publish your book with a publisher](./publisher.md) | +|:---:|:---:|:---:|:---:| +| Book changes over time, but you don't want to deal with versioning | | | | +| Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning | Recommended | | | +| Continuously adding content and solutions or updating crucial mistakes | | Recommended | | +| Allow referencing specific versions | Can be considered | Recommended | | +| Taylor-made book per academic year | Recommended | Recommended in case of students retaking a course | | +| Increase findability or benefit from publisher's brand | | | Recommended | + +Read more about each of these measures on the following sub-pages. \ No newline at end of file diff --git a/book/installation-and-setup/versioning_changelog.md b/book/installation-and-setup/versioning_changelog.md new file mode 100644 index 0000000..f0981b5 --- /dev/null +++ b/book/installation-and-setup/versioning_changelog.md @@ -0,0 +1,80 @@ +# TeachBooks versioning with changelog + +Versions combined with a changelog can be a very effective way to communicate book changes to the reader and allow reuse of specific versions. We recommend [TeachBooks versioning](../features/versioning.md), which comes in two flavors: + +1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form. An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions. +2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number. + +The details of TeachBooks versioning are covered [here](../features/versioning.md) + +## Changelog +To communicate changes, we advise creating a changelog in the book. The [template](https://github.com/TeachBooks/template/blob/main/book/changelog.md) contains an empty changelog to fill: + +```md +# Changelog + +## ``: `` +- `` [](``) +- ... +- Full Changelog: `[...]()' + +## ``: <...> +- <...> + +<...> +``` + +An example can be found [here](https://ciem5000-2025.github.io/book/changelog.html) + +## Note on version change on page +When making errata changes or additions, it's advised to notify the reader not only in the changelog, but also on the relevant pages. You can do so using the `versionadded` and `versionchanged` admonitions: + +```md +::::::{versionchanged} + +:::::: +``` + +and + +```md +::::::{versionadded} + +:::::: +``` + +Leads to for example: +::::::{versionchanged} v2025.3.5 2025-02-23 +TeachBooks versioning added +:::::: + +An example can be found [here](https://oit.tudelft.nl/CME4501/2024/pages/linear_constrained_optimization_class.html) + +## Implement tags and releases +Tags can be added to your source code by adding the version number as a tag to a specific commit. + +You can do so in GitHub when creating a new release (on the `Code` page of your repository.) There, you can enter a name for your tag and select one of your branches or recent commits: + +```{figure} figures/tags_github.png +--- +width: 500px +align: center +--- + +``` + +Locally, you can do so in GitHub Desktop by clicking 'Create Tag...` for a specific commit in the History tab. + +```{figure} figures/tags.png +--- +width: 500px +align: center +--- + +``` + +Once the tags is pushed to GitHub/GitLab. You can create a release of the version by clicking `Release` on the `Code` page of your repository. There you can select a tag and generate release notes. + +It's recommended to add the relevant part of the changelog to the release notes on GitHub. An example can be found [here](https://github.com/CIEM5000-2025/book/releases/tag/v2025.2.0) + + diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md new file mode 100644 index 0000000..836ebaf --- /dev/null +++ b/book/installation-and-setup/versions_URLs.md @@ -0,0 +1,23 @@ +# Publish version on separate (fixed) URLs + +As soon as you have different versions online, you have to make a decision about URLs. Using the [](../external/deploy-book-workflow/README.md), you can release the different version of your book all under the same root URL. So, it uses the same workflow as used for draft versions of your book as describe [before](draft_book), the only difference being that URLs of draft versions are generally not shared publicly. + +If you plan on maintaining only one public version, it is advisable to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy`. This ensures that the primary branch is copied to the root, making the URL more compact. + +To share the built book / website of old versions for your book on GitHub you have a few options: +- Create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: + - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same name. In that case. + - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers are redirected to a consistent URL, even when new versions of the book are added later. + - Eventually, you can add old branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state. Alternatively, you can add a banner manually to `_config.yml`, as explained [here](../basic-features/banner.md). + - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. + - If you have many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. + - An example can be found in the book 'Engineering Systems Optimization': it has two versions for readers online, the [2023-version](https://oit.tudelft.nl/CME4501/2023) and the [2024-version](https://oit.tudelft.nl/CME4501/2024), recognizable by the URL. Both versions originate from their respective branches in the [GitHub-repository](https://github.com/TUDelft-books/CME4501) +- Add a zip of the built book to the release in GitHub as binary asset. This requires readers to download the zip and open the html files locally, but doesn't require you to host it somewhere. This zip can be easily downloaded as an artifact from [the GitHub action](../external/deploy-book-workflow/README.md). An example can be found [here](https://github.com/TUDelft-books/CME4501/releases/tag/v2024.1.0). Note that this requires you to set up tags and releases, as explained in [](versioning_changelog.md) +- Use [Read the Docs](../features/pull_request_build.md) to build a website for all your branches, forks and tags as Read the docs doesn't have a 1 GB limit, but has a very different URL structure and the free community version has advertisement. In case you're using tags and releases, refer to the URL of this built from your GitHub release to make sure that GitHub visitors find their way to Read the Docs. + +If you have your own webserver, you can publish each version on it manually. + +Don't forget to explain how you organize your URLs and old versions in your README and eventually in the book itself too with a sentence like this (as can be seen in [this book](https://oit.tudelft.nl/CME4501/2024/intro.html) too): + +> This is the ``-version of this book. Go to `` to view the most recent version of this book, or adapt the year in `/` to the year when you took the course. + diff --git a/book/intro/template.md b/book/intro/template.md index 118547d..9e4fb0c 100644 --- a/book/intro/template.md +++ b/book/intro/template.md @@ -26,9 +26,9 @@ Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBoo ``` ## 3. Let's practice! -Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. +Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. -The exercises can be found in your book at `https://.github.io//exercises/exercises` (case sensitive) or at https://teachbooks.io/template/exercises.html. +The exercises on the TeachBooks Workflow can be found in your book at `https://.github.io//exercises/exercises` (case sensitive) or at https://teachbooks.io/template/exercises.html. ```{figure} https://raw.githubusercontent.com/TeachBooks/template_figures/refs/heads/main/exercises.png --- diff --git a/book/references.bib b/book/references.bib index bda464b..3b54aed 100644 --- a/book/references.bib +++ b/book/references.bib @@ -133,4 +133,12 @@ url = {https://github.com/TeachBooks/Sphinx-Named-Colors}, year = {2024}, note = {Retrieved January 2025. MIT.} -} \ No newline at end of file +} + +@misc{semver, + author = {Tom Preston-Werner}, + title = {Semantic Versioning specification}, + url = {https://semver.org/}, + year = {2025}, + note = {Retrieved February 2025. CC BY 3.0.} +} diff --git a/requirements.txt b/requirements.txt index e0559d4..1d686bb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,7 +7,7 @@ sphinx-image-inverter == 1.1.2 sphinx-exercise == 1.0.1 sphinx-proof == 0.2.0 sphinx-named-colors == 1.0.1 -sphinx-iframes == 1.0.3 +sphinx-iframes == 1.0.5 sphinx-prime-applets == 1.0.1 git+https://github.com/TeachBooks/Sphinx-Thebe