diff --git a/book/credits.md b/book/credits.md index 51b3ab4..7e00316 100644 --- a/book/credits.md +++ b/book/credits.md @@ -63,7 +63,7 @@ The following pages contain content written by others, part of has been reused a - 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. - +- page [](./features/external_toc.md): includes text from {cite:t}`teachbooks_package` that has been modified. Original content licensed under MIT. diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 40c28fc..b814e24 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -1,4 +1,9 @@ ````{margin} +```{attributiongrey} Attribution +:class: attribution +This page reuses MIT licensed content from {cite:t}`teachbooks_package`. {fa}`quote-left`{ref}`Find out more here.` +``` + ```{admonition} User types :class: tip This page is useful for user type 3-5. @@ -22,7 +27,7 @@ The External TOC features are incorporated in the teachbooks package starting wi ## What does it do? -This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb`, `.md` and `.rst` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it validates that the external content has a permissive license, automatically combines any `reference.bib` files, and warns you if there's a mismatch in `requirements.txt` or with plugins in `_config.yml`. +This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb`, `.md` and `.rst` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it validates that the external content has a permissive license, automatically combines any `reference.bib` files, and warns you if there's a mismatch in `requirements.txt` or with plugins in `_config.yml`. Furthermore, it adds an attribution admonition (like the one on this page) to the page, showing the source of the file in the built book. To ease the process, the webapp [TeachBooks Recombiner](https://teachbooks.io/recombiner/) allows you to select the pages to take from other books and generate the syntax to add them to your book. @@ -76,6 +81,42 @@ If you're building your book online in GitHub, the [deploy-book-workflow](../ext If the source file is from another book, the contents of the `requirements.txt`, `_config.yml` are checked for any missing/incompatible entries. If this leads to compatibility issue, you'll be warned during the build which will help you solve these dependencies or plugins manually by updating your main book's `_config.yml` and `requirements.txt` Additionally, any `references.bib` files are merged into your main book's `references.bib` file, and the licenses of the external content are validated to allow for re-use. External content without a permissive license will result in an error to try to prevent any accidental copyright infringement. +### Configuration +The attribution admonition can be configured in the `_config.yml` file. You can adapt the location (top or margin), colour (making use of the sphinx extension [Sphinx-Named-Colors](../external/Sphinx-Named-Colors/README.md)), and symbol (by adding a custom CSS class). This leads to a similar admonition as mentioned [in the chapter on recommendations for copyright and licenses](custom_attribution). + +To adapt the location of the admonition (margin or top, top is default option), you can use the following configuration: + +```yaml +teachbooks: + attribution_location: margin +``` + +To adapt the colour of the admonition (with for example a grey colour, default is blue), you can use the following configuration. Make sure to add the `sphinx-named-colors` extension to your environment (e.g., `requirements.txt`): + +```yaml +sphinx: + config: + named_colors_custom_colors: {'attributiongrey':[150,150,150]} + extra_extensions: + - sphinx_named_colors + +teachbooks: + attribution_color: attributiongrey +``` + +To adapt the symbol of the admonition (with for example double quotes), you can add the following [custom CSS class](../_static/attribution.css) to `book/_static/attribution.css`: + +```css +/* Attribution */ +div.attribution > .admonition-title::after { + content: "\f10d"; +} +``` + +Note that, when making a changes for the configuration locally they are not incorporated to existing external content. +You will need to remove the `_git/` folder and re-run the build command to see the changes. When building the book on i.e. GitHub Actions, the `_git/` folder is always rebuild from scratch. + + ## Contribute This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/TeachBooks). diff --git a/book/installation-and-setup/copyright/recommendations.md b/book/installation-and-setup/copyright/recommendations.md index c018533..68a0fd7 100644 --- a/book/installation-and-setup/copyright/recommendations.md +++ b/book/installation-and-setup/copyright/recommendations.md @@ -73,6 +73,7 @@ This produces > This page reuses CC BY content from {cite:t}`jason_moore`. {fa}`quote-left`{ref}`Find out more here.` +(custom_attribution)= ##### Format as custom admonition The previous syntax might be used for other purposes as well. An alternative is a custom attribution admonition: diff --git a/book/references.bib b/book/references.bib index fd81c05..ed12b0f 100644 --- a/book/references.bib +++ b/book/references.bib @@ -157,4 +157,12 @@ url = {https://github.com/TeachBooks/Sphinx-PRIME-applets}, year = {2025}, note = {Retrieved April 2025. MIT.} +} + +@misc{teachbooks_package, + author = {{TeachBooks}}, + title = {TeachBooks Package: Jupyter Book Wrappe}, + url = {https://github.com/TeachBooks/TeachBooks}, + year = {2024}, + note = {Retrieved April, 2025. MIT License.} } \ No newline at end of file