Skip to content

Commit dbb8f2a

Browse files
oestebanoesteban
committed
enh: improve rendering of code examples, minimal additions
1 parent aaf48f6 commit dbb8f2a

File tree

2 files changed

+74
-64
lines changed

2 files changed

+74
-64
lines changed

‎docs/community/licensing.md

Lines changed: 72 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
# Licensing and Derived Works
22

33
All software packages and tools under the *NiPreps* umbrella must be licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) by default, unless otherwise stated.
4-
The authors of new packages may not abide by this general rule of thumb if necessary and/or sufficiently justified (e.g., the source code is actually derived from a product licensed under a copyleft license).
4+
The authors of new *NiPreps* packages may not abide by this general rule of thumb if necessary and/or sufficiently justified (e.g., the source code is actually derived from a product licensed under a copyleft license).
5+
56
Data (distributed within the test data of packages or through the [`nipreps-data` GitHub organization](https://github.com/nipreps-data)) will preferably be distributed under the [Creative Commons Zero v1.0 Universal](https://choosealicense.com/licenses/cc0-1.0/).
67

8+
Under no circumstances any *NiPreps* software or data will be made publicly available unlicensed.
9+
If you find any component of *NiPreps* that is unlicensed, please make us aware at [email protected] at your earliest convenience.
10+
711
## The Apache License 2.0
812

913
(This section is adapted from this [blog post by D. Marín](https://www.toptal.com/open-source/developers-guide-to-open-source-licenses))
@@ -54,72 +58,78 @@ The *high-level description of the changes* will preferably contain:
5458
## Example of our expectations
5559

5660
Let's say a Derived Work modifies the `sdcflows.viz.utils` code-base.
61+
Some files may not have the attribution notice.
5762
At the time of writing, the header comment of [this file](https://github.com/nipreps/sdcflows/blob/50393a8584dd0abf5f8e16e6ba66c43e1126f844/sdcflows/viz/utils.py) is:
5863

59-
``` {.python linenos=true title="Original Work header comment"}
60-
# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
61-
# vi: set ft=python sts=4 ts=4 sw=4 et:
62-
#
63-
# Copyright 2021 The NiPreps Developers <[email protected]>
64-
#
65-
# Licensed under the Apache License, Version 2.0 (the "License");
66-
# you may not use this file except in compliance with the License.
67-
# You may obtain a copy of the License at
68-
#
69-
# http://www.apache.org/licenses/LICENSE-2.0
70-
#
71-
# Unless required by applicable law or agreed to in writing, software
72-
# distributed under the License is distributed on an "AS IS" BASIS,
73-
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
74-
# See the License for the specific language governing permissions and
75-
# limitations under the License.
76-
"""Visualization tooling."""
77-
```
78-
79-
Some files may not have the attribution notice, for example:
80-
``` {.python linenos=true title="Original Work header comment"}
81-
# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
82-
# vi: set ft=python sts=4 ts=4 sw=4 et:
83-
"""Visualization tooling."""
84-
```
64+
!!! example "Header comment in the original Work"
65+
66+
=== "With attribution notice"
67+
```{.python}
68+
# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
69+
# vi: set ft=python sts=4 ts=4 sw=4 et:
70+
#
71+
# Copyright 2021 The NiPreps Developers <[email protected]>
72+
#
73+
# Licensed under the Apache License, Version 2.0 (the "License");
74+
# you may not use this file except in compliance with the License.
75+
# You may obtain a copy of the License at
76+
#
77+
# http://www.apache.org/licenses/LICENSE-2.0
78+
#
79+
# Unless required by applicable law or agreed to in writing, software
80+
# distributed under the License is distributed on an "AS IS" BASIS,
81+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
82+
# See the License for the specific language governing permissions and
83+
# limitations under the License.
84+
"""Visualization tooling."""
85+
```
86+
=== "Without attribution notice"
87+
```{.python}
88+
# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
89+
# vi: set ft=python sts=4 ts=4 sw=4 et:
90+
"""Visualization tooling."""
91+
```
8592

8693
Either way (whether the attribution notice is present or not), we suggest to update this header comment to something along the lines of the following:
8794

88-
``` {.python linenos=true title="Derived Work header comment"}
89-
# <shebang and editor settings can be preserved or removed freely>
90-
#
91-
# <your attribution notice, either maintaining the Apache-2.0 license or changing the license>
92-
#
93-
# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,
94-
# and this file has been changed.
95-
# <recommended> The original file this work derives from is found at:
96-
# https://github.com/nipreps/sdcflows/blob/50393a8584dd0abf5f8e16e6ba66c43e1126f844/sdcflows/viz/utils.py
97-
# <alternative> The original file this work derives from is found within
98-
# the version 2.0.2 distribution of the software.
99-
#
100-
# <recommended> [April 2021] CHANGES:
101-
# * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.
102-
# * ENH: Changed plotting dependency to the new `netplotbrain` package.
103-
# * DOC: Added docstrings to some functions that lacked them.
104-
#
105-
# ORIGINAL WORK'S ATTRIBUTION NOTICE:
106-
#
107-
# Copyright 2021 The NiPreps Developers <[email protected]>
108-
#
109-
# Licensed under the Apache License, Version 2.0 (the "License");
110-
# you may not use this file except in compliance with the License.
111-
# You may obtain a copy of the License at
112-
#
113-
# http://www.apache.org/licenses/LICENSE-2.0
114-
#
115-
# Unless required by applicable law or agreed to in writing, software
116-
# distributed under the License is distributed on an "AS IS" BASIS,
117-
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
118-
# See the License for the specific language governing permissions and
119-
# limitations under the License.
120-
"""Visualization tooling."""
121-
```
122-
95+
!!! example "Suggested header comment in the Derived Work"
96+
97+
``` {.python hl_lines="5 6 19 20 21 22 23 24 25 26 27 28 29 30 31"}
98+
# <shebang and editor settings can be preserved or removed freely>
99+
#
100+
# <your attribution notice, either maintaining the Apache-2.0 license or changing the license>
101+
#
102+
# STATEMENT OF CHANGES: This file is derived from sources licensed under the Apache-2.0 terms,
103+
# and this file has been changed.
104+
# <recommended> The original file this work derives from is found at:
105+
# https://github.com/nipreps/sdcflows/blob/50393a8584dd0abf5f8e16e6ba66c43e1126f844/sdcflows/viz/utils.py
106+
# <alternative> The original file this work derives from is found within
107+
# the version 2.0.2 distribution of the software.
108+
#
109+
# <recommended> [April 2021] CHANGES:
110+
# * BUGFIX: Outdated function call from the ``svgutils`` dependency that changed API as of version 0.3.2.
111+
# * ENH: Changed plotting dependency to the new `netplotbrain` package.
112+
# * DOC: Added docstrings to some functions that lacked them.
113+
#
114+
# ORIGINAL WORK'S ATTRIBUTION NOTICE:
115+
#
116+
# Copyright 2021 The NiPreps Developers <[email protected]>
117+
#
118+
# Licensed under the Apache License, Version 2.0 (the "License");
119+
# you may not use this file except in compliance with the License.
120+
# You may obtain a copy of the License at
121+
#
122+
# http://www.apache.org/licenses/LICENSE-2.0
123+
#
124+
# Unless required by applicable law or agreed to in writing, software
125+
# distributed under the License is distributed on an "AS IS" BASIS,
126+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
127+
# See the License for the specific language governing permissions and
128+
# limitations under the License.
129+
"""Visualization tooling."""
130+
```
131+
132+
Only the lines highlighted are explicitly required by the Apache-2.0 conditions.
123133
Although it is not mandated by the license letter, the spirit of the Apache-2.0 (and all other licenses stipulating the statement of changes, such as the CC-BY 4.0) suggests that a date of modification and an overview of outstanding changes are pertinent.
124134
We also suggest a link to the original code, including the commit-hash (that long string starting with `50393a` in the URL above) for the location of the exact origin of the file.
125135
Alternatively, Derived Works may point to a exact release identifier where the original file is part of the code-base distribution.

‎mkdocs.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,14 +36,14 @@ theme:
3636

3737
markdown_extensions:
3838
- admonition
39-
- codehilite
40-
- fenced_code
4139
- footnotes
4240
- toc:
4341
permalink: true
4442
- pymdownx.emoji:
4543
emoji_index: !!python/name:materialx.emoji.twemoji
4644
emoji_generator: !!python/name:materialx.emoji.to_svg
45+
- pymdownx.tabbed
46+
- pymdownx.highlight
4747
- pymdownx.superfences
4848
- pymdownx.snippets
4949
- markdown_include.include:

0 commit comments

Comments
 (0)