Developer Guide¶
This guide provides technical details on building the book and documentation. It also outlines general rules, format and page structure for authoring and contributing documentation and book content. To streamline the process, please read this document carefully before committing any time to the project.
Project Structure¶
The project source is hosted on GitHub in the xmlx-dev/xml-book repository. There are four main components of this project’s file structure:
- setup files (GitHub repository, Binder, etc.);
- support tools and configuration files;
- book source files; and
- documentation source files.
Setup Files¶
.
├── .binder
│ └── requirements.txt
├── .github
│ ├── ISSUE_TEMPLATE
│ │ ├── book_content_issue.md
│ │ ├── book_technical_issue.md
│ │ ├── config.yml
│ │ ├── docs_issue.md
│ │ └── technical_issue.md
│ ├── PULL_REQUEST_TEMPLATE
│ │ └── generic_pr.md
│ ├── workflows
│ │ ├── build-and-deploy.yml
│ │ └── cla-assistant.yml
│ └── config.yml
├── .gitignore
├── .nojekyll
├── CITATION.cff
├── CNAME
├── LICENCE
├── LICENCE-code
└── README.md
This part of the project source provides:
- configuration of Binder requirements (
.binder/requirements.txt) - templates for and configuration of GitHub Issues (
.github/ISSUE_TEMPLATE) - templates for GitHub Pull Requests (
.github/PULL_REQUEST_TEMPLATE) -
configuration of GitHub Actions (
.github/workflows)build-and-deploy.ymlis responsible for testing and building the book and the documentation, and deploying them to GitHub Pages, which are served from themasterbranch of the xmlx-dev/xml-book-page repositorycla-assistant.ymlprompts users to sign Contributor Licence Agreement via comments in GitHub Pull Requests; it is based on the CLA Assistant GitHub Action
-
miscellaneous configuration of the GitHub repository (
.github/config.yml) - a list of files for git to ignore (
.gitignore) - GitHub Pages configuration file indicating that the webpage should not be
built with Jekyll (
.nojekyll) - citation file for the repository (
CITATION.cff) - GitHub Pages configuration file specifying our custom domain
(https://book.xmlx.dev) under which the book is published (
CNAME) - licence for the book (
LICENCE) - licence for the code (
LICENCE-code) - general information about the repository and its content (
README.md)
Tools and Scripts¶
.
├── requirements-tools.txt
└── tools
├── fn.sh
├── get_book_version.py
├── pyspelling.yml
├── pyspelling_en_GB-custom.txt
├── pyspelling_filters_git.py
├── pyspelling_filters_ipynb.py
├── wording.py
└── wording.yml
The second group of source files includes:
- a list of Python packages required for running the support tools
(
requirements-tools.txt) - a collection of Bash scripts to automate various tasks (
tools/fn.sh) – see the Automation section for more details - a tool that checks whether the book version used by the Jupyter Book and MkDocs configuration files as well as the citation file and the latest entry in the changelog and are all the same; it also checks whether the copyright year used by the Jupyter Book and MkDocs are the same and up to date
-
automated spell-checking resources (
toolsdirectory)pyspelling.ymlconfigures the PySpelling Python packagepyspelling_en_GB-custom.txtextends the British English dictionary with a lists of custom wordspyspelling_filters_git.pydefines a custom filter for the PySpelling Python package to only process files that are tracked by gitpyspelling_filters_ipynb.pydefines a custom filter for the PySpelling Python package to extract Markdown cells of Jupyter Notebooks
-
automated checking of wording used by the book (
toolsdirectory)wording.pyprocesses the book source documents and the built HTML tree in search of undesired wordswording.ymllists words that must not appear in the text, either at all or their spelling that should be used
Documentation Source¶
.
├── CLA.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── docs
│ ├── cla.md -> ../CLA.md
│ ├── conduct.md -> ../CODE_OF_CONDUCT.md
│ ├── dev.md -> ../CONTRIBUTING.md
│ ├── book_templates
│ │ └── ...
│ └── ...
├── mkdocs.yml
└── requirements-docs.txt
The documentation source tree consists of:
- Contributor Licence Agreement
(
CLA.md) - Code of Conduct (
CODE_OF_CONDUCT.md) - guidelines for contributing to the project
(
CONTRIBUTING.md– the source of this document) - a collection of documentation source files (the
docsdirectory); to access the source file underlying any documentation page click the button appearing in the top-right corner of each pagebook_templatesholds content templates for the book
- configuration of the MkDocs documentation builder and the
Material for MkDocs template (
mkdocs.yml) - a list of Python packages required for building the documentation
(
requirements-docs.txt)
Book Source¶
.
├── _config.yml
├── _ext
│ └── bibtex_iclr.py
├── _static
│ └── xmlx.css
├── _toc.yml
├── book
│ └── ...
└── requirements-book.txt
The book source tree consists of:
- Jupyter Book configuration (
_config.yml) -
bespoke extensions of Jupyter Book (the
_extdirectory)bibtex_iclr.pyspecifies a custom citation and referencing style for the book
-
static files to be included in the HTML book build (the
_staticdirectory)xmlx.cssdefines custom CSS styles to be used with the book
-
table of content structure and specification (
_toc.yml) - a collection of book source files (the
bookdirectory); to access the source file underlying any book page click the :fontawesome-solid-pencil-alt: button appearing in the drop-down menu located in the top-right corner of each page - a list of Python packages required for building the book
(
requirements-book.txt)
Contributing to the Project¶
Project contributions are governed by our Code of Conduct and subject to acceptance of the repository licences and our Contributor Licence Agreement. We have put in place a dedicated contribution workflow (outlined by this document) to streamline the entire process.
Licencing and Agreements¶
The book is licenced under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.
Book Licence
Attribution-NonCommercial-ShareAlike 4.0 International
Copyright (c) 2021, Kacper Sokol
All rights reserved.
=======================================================================
Human-readable summary of the license:
https://creativecommons.org/licenses/by-nc-sa/4.0/
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are
intended for use by those authorized to give the public
permission to use material in ways otherwise restricted by
copyright and certain other rights. Our licenses are
irrevocable. Licensors should read and understand the terms
and conditions of the license they choose before applying it.
Licensors should also secure all rights necessary before
applying our licenses so that the public can reuse the
material as expected. Licensors should clearly mark any
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
licensed material under specified terms and conditions. If
the licensor's permission is not necessary for any reason--for
example, because of any applicable exception or limitation to
copyright--then that use is not regulated by the license. Our
licenses grant only permissions under copyright and certain
other rights that a licensor has authority to grant. Use of
the licensed material may still be restricted for other
reasons, including because others have copyright or other
rights in the material. A licensor may make special requests,
such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
Public License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution-NonCommercial-ShareAlike 4.0 International Public License
("Public License"). To the extent this Public License may be
interpreted as a contract, You are granted the Licensed Rights in
consideration of Your acceptance of these terms and conditions, and the
Licensor grants You such rights in consideration of benefits the
Licensor receives from making the Licensed Material available under
these terms and conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. BY-NC-SA Compatible License means a license listed at
creativecommons.org/compatiblelicenses, approved by Creative
Commons as essentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
e. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
f. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name
of a Creative Commons Public License. The License Elements of this
Public License are Attribution, NonCommercial, and ShareAlike.
h. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
i. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
k. NonCommercial means not primarily intended for or directed towards
commercial advantage or monetary compensation. For purposes of
this Public License, the exchange of the Licensed Material for
other material subject to Copyright and Similar Rights by digital
file-sharing or similar means is NonCommercial provided there is
no payment of monetary compensation in connection with the
exchange.
l. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
m. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
n. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part, for NonCommercial purposes only; and
b. produce, reproduce, and Share Adapted Material for
NonCommercial purposes only.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. Additional offer from the Licensor -- Adapted Material.
Every recipient of Adapted Material from You
automatically receives an offer from the Licensor to
exercise the Licensed Rights in the Adapted Material
under the conditions of the Adapter's License You apply.
c. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties, including when
the Licensed Material is used other than for NonCommercial
purposes.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
b. ShareAlike.
In addition to the conditions in Section 3(a), if You Share
Adapted Material You produce, the following conditions also apply.
1. The Adapter's License You apply must be a Creative Commons
license with the same License Elements, this version or
later, or a BY-NC-SA Compatible License.
2. You must include the text of, or the URI or hyperlink to, the
Adapter's License You apply. You may satisfy this condition
in any reasonable manner based on the medium, means, and
context in which You Share Adapted Material.
3. You may not offer or impose any additional or different terms
or conditions on, or apply any Effective Technological
Measures to, Adapted Material that restrict exercise of the
rights granted under the Adapter's License You apply.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database for NonCommercial purposes
only;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material,
including for purposes of Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.
Contributors are required to accept and sign
Apache Individual Contributor Licence Agreement 2.2.
This process is managed by the CLA Assistant GitHub Action
(configured in the .github/workflows/cla-assistant.yml workflow file),
which prompts new contributors to read and sign the
Contributor Licence Agreement (CLA) directly within the relevant
GitHub Pull Request.
The list of CLA signatures is stored in a private GitHub repository
(xmlx-dev/cla) for our record;
the automation is achieved through the xmlx-concierge
GitHub bot account.
Contributor Licence Agreement
Individual Contributor Licence Agreement (“Agreement”)
Adapted from the Apache Individual Contributor License Agreement V2.2. See the Apache Contributor Agreements page for more details.
Thank you for your interest in XMLX. To clarify the intellectual property licence granted with Contributions from any person or entity, XMLX must have on file a digitally signed Contributor Licence Agreement (“CLA”) from each Contributor, indicating agreement with the licence terms below. This agreement is for your protection as a Contributor as well as the protection of XMLX and its users. It does not change your rights to use your own Contributions for any other purpose. Read this document carefully before digitally signing and keep a copy for your records.
You accept and agree to the following terms and conditions for Your Contributions (present and future) that you submit to XMLX. Except for the licence granted herein to XMLX and recipients of software and materials distributed by XMLX, You reserve all right, title, and interest in and to Your Contributions.
-
Definitions.
“You” (or “Your”) shall mean the copyright owner or legal entity authorised by the copyright owner that is making this Agreement with XMLX. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, “control” means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
“Contribution” shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to XMLX for inclusion in, or documentation of, any of the products owned or managed by XMLX (the “Work”). For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to XMLX or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, XMLX for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as “Not a Contribution.”
-
Grant of Copyright Licence.
Subject to the terms and conditions of this Agreement, You hereby grant to XMLX and to recipients of software and materials distributed by XMLX a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright licence to reproduce, prepare derivative works of, publicly display, publicly perform, sublicence, and distribute Your Contributions and such derivative works.
-
Grant of Patent Licence.
Subject to the terms and conditions of this Agreement, You hereby grant to XMLX and to recipients of software and materials distributed by XMLX a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent licence to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such licence applies only to those patent claims licencable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licences granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
-
You represent that you are legally entitled to grant the above licence. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer has waived such rights for your Contributions to XMLX, or that your employer has executed a separate Corporate CLA with XMLX.
-
You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party licence or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.
-
You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
-
Should You wish to submit work that is not Your original creation, You may submit it to XMLX separately from any Contribution, identifying the complete details of its source and of any licence or other restriction (including, but not limited to, related patents, trademarks, and licence agreements) of which you are personally aware, and conspicuously marking the work as “Submitted on behalf of a third-party: [named here].”
-
You agree to notify XMLX of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.
By digitally signing this agreement through this GitHub Pull Request interaction, You accept and agree with its content.
This is a legal contract containing Personally Identifiable Information. We retain the details of your agreement in a private GitHub repository only for administrative purposes beyond which this information will not be used or shared.
This arrangement allows us to offer the book online for free for personal, educational and other not-for-profit purposes.
The code is licenced under MIT.
Code Licence
Copyright 2021 Kacper Sokol
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
GitHub Workflow¶
Please use GitHub Issues to report problems pertaining to this repository. Choose one of the pre-defined issue templates; it will guide you through the reporting process. We have templates for problems with:
- the book content,
- technical infrastructure of the book,
- technical aspects and content of the documentation, and
- technical infrastructure of the repository.
Prior to opening an issue, make sure that the reported problem is not already covered by one of the existing issues. If you would like to discuss the problem before opening an issue, you can use our GitHub Discussion board or get in touch via any other suitable communication channel.
If you wish to contribute to the project, you must open an issue first to discuss the envisaged changes and additions. This procedure is in place to ensure that work is not duplicated and that the proposed changes will make it into the book release (otherwise we cannot guarantee accepting your contributions). Also, once the outline of the contribution is agreed, other people can more easily join in to help with the development and make the most out of everybody’s time commitment. Furthermore, this workflow allows us to maintain excellent quality of the content, its factual correctness and adherence to our book and documentation contribution guidelines.
Any contributions should be submitted as GitHub Pull Requests against
the dev branch of the xmlx-dev/xml-book
repository from your personal fork of the codebase – see the following
sections for more details.
To get an inspiration for a contribution, have a look at our work plan by navigating to GitHub Projects, where we maintain a simple kanban-esque board.
Development Environment Setup¶
Most of the tools and workflows utilised by this project are written in Python.
Consider using Python virtual environments (e.g., pyenv with
pyenv-virtualenv) for setting up your development environment.
Code Repository¶
You should start by forking the xmlx-dev/xml-book GitHub repository. Next, clone it onto your local machine and enter the source directory
git clone git@github.com:<your GitHub user ID>/xml-book.git
cd xml-book
dev branch, and create a new branch
for your contributions
git checkout dev
git checkout -b my-contribution-branch
dev, as this source
tree holds the latest version of the book (which may have not necessarily been
released yet).
Consider setting up pre-commit git hooks to ensure that your individual contributions are consistent with our quality standards.
When you are done with your contributions, open a GitHub Pull Request
from the feature branch in your fork (my-contribution-branch) onto the
dev branch in the main repository
(xmlx-dev/xml-book).
Building the Documentation¶
To build the documentation, you need to have relevant Python packages installed. You can do this with
pip install -r requirements-docs.txt
mkdocs serve
mkdocs build -s -d ./_build/docs
./_build/docs directory.
Building the Book¶
To build the book, you need to have relevant Python packages installed. You can do this with
pip install -r requirements-book.txt
jb build -nW ./
./_build/html directory.
Alternatively, you may serve the book website with the builtin Python
HTTP server, like so
python -m http.server ./_build/html
XML Book Code
In addition to popular Python libraries, the book is supported by a bespoke library (xmlx-dev/xml-book-code) that implements functionality streamlining content creation. For more information see the Execution Environment Settings section below.
Automation¶
To help automate and streamline some development tasks, the repository is shipped with a collection of helper functions. These require some relevant Python packages to be installed on your system
pip install -r requirements-tools.txt
aspell spell-checking software installed
(the following command is for Ubuntu Linux)
apt-get install -y aspell aspell-en
aspell,
e.g., brew install aspell for MacOS.)
These functions are invoked through the ./tools/fn.sh Bash scrip with
./tools/fn.sh <function_name>
./tools/fn.sh check_spelling.
Installing Pre-Commit Git Hooks¶
Pre-commit git hooks are scripts executed before every commit; if any of them fails, you will not be allowed to commit your changes. This quality-checking system helps you to maintain high standards of your contributions along the way, thus saving you from fixing all of the small errors when opening a pull request. To set them up execute
./tools/fn.sh setup_git_hooks
To disable pre-commit hooks, comment out relevant lines in the
.git/hooks/pre-commit file.
If you want to commit changes without running pre-commit hooks, add the -n
flag (--no-verify) to your git commit command.
(Make sure that you do not abuse this flag as side-stepping pre-commit
checks can lead to a build-up of errors that will need to be fixed prior to
merging your changes.)
Checking Cleanliness of Jupyter Notebooks¶
Since our book environment (Jupyter Book) supports content written in (MyST) Markdown and Jupyter Notebooks (among many others formats), we need to ensure that the source files are clean. This is particularly important for Jupyter Notebook, which may contain cell execution artefacts (output) and metadata. To maintain a small footprint of the book source and avoid unexpected build errors, Jupyter Notebooks committed to the repository should be clean. You can check the status of your notebooks with the following command (which is also executed as one of the pre-commit hooks)
./tools/fn.sh check_clean_ipynb
./tools/fn.sh clean_ipynb
Spell-Checking¶
Given the textual nature of the project, it is important to ensure a correct
and consistent spelling throughout.
We achieve this with PySpelling – a Python automation framework built
around aspell.
You can check the spelling of all the relevant project files like so
./tools/fn.sh check_spelling
If you find that a certain word is missing from the spell-check dictionary,
you can extend it by placing the word in question in the
tools/pyspelling_en_GB-custom.txt file.
This list of words must be sorted alphanumerically (case insensitive) and it
extends the standard British English dictionary.
Checking Wording of the Book¶
We also have a list of words that should be avoided as well as preferred spelling for certain words and phrases, e.g., “data set” instead of “dataset”. You can check the book – both its source files and the built HTML tree – like so (which is also run as one of the pre-commit hooks)
./tools/fn.sh check_wording
tools/wording.yml file.
Checking for Leftover TODO Markers¶
Additionally, you can check whether any file in the repository has a leftover,
case-insensitive “todo” keyword with the check_todos script.
./tools/fn.sh check_todos
Validating Version and Year¶
Since the version of the book is stored in multiple places, a custom script is used to ensure their consistency. The versions listed in the Jupyter Book and MkDocs configuration files are compared against the citation file and the latest entry in the changelog. The copyright year placed in both configuration files is also compared against the current year. These operations are executed with
./tools/get_book_version.py
Build Aliases¶
The ./tools/fn.sh Bash script also implements a collection of shortcuts
for common build tasks:
build_bookbuilds the book,linkcheck_bookchecks whether all of the links placed in the book are accessible,build_docsbuilds the documentation,link_docsintegrates the documentation build (static HTML website) into the book build (by copying the_build/docsdirectory into the_build/html/directory),buildbuilds the book and the documentation, and links the two.
XML Book Python Package¶
The book is accompanied by the bespoke xml_book Python module,
whose implementation can be found in the
xmlx-dev/xml-book-code GitHub repository.
It should be imported along with other needed packages at the top of each
book file in a dedicated code cell tagged with remove-cell to hide it in the
rendered document.
(The example below is for files in the MyST Markdown format.)
```{code-cell} python
---
tags: [remove-cell]
---
import xml_book
```
If you need to extend the package while working on the book, you can clone
the code repository into a folder named _code, which is ignored by git
and excluded from Jupyter Book builds.
git clone git@github.com:xmlx-dev/xml-book-code.git _code
pip install -e _code
Execution Environment Settings¶
Importantly, the XML-Book-Code package allows to apply consistent settings
to each page of the book.
The xml_book.config module implements various environment setup functions,
which are then invoked from the initialisation file – xml_book/__init__.py
– of the xml_book library.
For example, to unify the look of plots, the xml_book.config.setup_plotting
function is executed automatically upon package import, ensuring that the
figures are in the seaborn style and rendered as SVGs.
To apply the settings defined by the xml_book module, it needs to be imported
on each individual page that makes use of programmatically generated content.
Setting Up Python Environment
To load global settings of the Python environment used to generate book
content through execution of Python scripts, load the xml_book module.
To this end, insert a hidden code cell into your MyST Markdown content
file.
```{code-cell} python
---
tags: [remove-cell]
---
import xml_book
```
Known Issues¶
There are some known issues with the software stack used for generating the book, which either prevent using certain functionality or require a workaround.
- It is impossible to specify global
settings of the iPython environment
(e.g.,
c.InlineBackend.figure_formats = {'svg'}) used to execute Python code in parts of the book that make use of programmatically-generated content – see this GitHub issue. The workaround is applied by configuring the execution environment from within the custom XML-Book-Code Python package. - The
MyST-NBpackage responsible for executing Python code included in MyST Markdown content files has a bug that does not allow to include more than two Python-generated figures in a single file if more than one of them has an ID assigned with thenameparameter.See these two GitHub issues: (1), (2).```{code-cell} python --- render: image: width: 300px alt: Figure description. figure: caption: | Figure caption. name: 'fig:reference:id' ``` - Dropdown admonitions take too much space when collapsed if a table is placed inside. This GitHub issue appears related.