Skip to content

Commit fa5a6ac

Browse files
committed
Fix: add footnotes to the install lesson
1 parent 7adf1c4 commit fa5a6ac

File tree

1 file changed

+15
-5
lines changed

1 file changed

+15
-5
lines changed

tutorials/1-installable-code.md

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ To complete this lesson you will need a local Python
4545
environment and shell on your computer.
4646

4747
You are welcome to use any Python environment manager that you choose.
48-
If you are using Windows or are not familiar with Shell, you may want to [consult the Carpentries shell lesson.](https://swcarpentry.github.io/shell-novice/). Windows users will likely need to configure a tool for any Shell and git related steps.
48+
If you are using Windows or are not familiar with Shell, you may want to check out the Carpentries shell lesson[^shell-lesson]. Windows users will likely need to configure a tool for any Shell and git related steps.
4949

5050
* [If you need guidance creating a Python environment, review this lesson](extras/1-create-environment.md) which walks you through creating an environment using both `venv` and `conda`.
5151
* If you aren't sure which environment manager to use and
@@ -213,9 +213,7 @@ When you see the word module, we are referring to a `.py` file containing Python
213213
code.
214214

215215
The `__init__.py` allows Python to recognize that a directory contains at least one (1) module that may be imported and used in your code.
216-
A package can have multiple modules.
217-
218-
[Learn more about Python packages and modules in the Python documentation.](https://docs.python.org/3/tutorial/modules.html#packages )
216+
A package can have multiple modules[^python-modules].
219217

220218
:::
221219

@@ -236,7 +234,9 @@ If you are following along and making a Python package from scratch then you can
236234
1. It has a [numpy-style docstring](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html#three-python-docstring-formats-and-why-we-like-numpy-style)
237235
2. It uses [typing](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html#adding-type-hints-to-your-docstrings)
238236

239-
Python can support many different docstrings formats depending on the documentation build system you wish to use. The most popular supported formats for documenting Python objects are [NumPy Style Docstring](https://numpydoc.readthedocs.io/en/latest/format.html), [Google Style Docstring](https://google.github.io/styleguide/pyguide.html), [ReStructuredText Style Docstring](https://peps.python.org/pep-0287/), and the [Epytext Style Docstrings](https://epydoc.sourceforge.net/epytext.html). **pyOpensci recommends using the NumPy Docstring convention.**
237+
Python can support many different docstrings formats depending on the documentation build system you wish to use. The most popular supported formats for documenting Python objects are NumPy Style Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext Style Docstrings[^epytextdoc].
238+
239+
**pyOpensci recommends using the NumPy Docstring convention.**
240240

241241
If you aren’t familiar with docstrings or typing yet, that is ok. We will get to it later in our tutorial series. Or, you can review the pyOpenSci [packaging guide](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html) for an overview.
242242

@@ -475,3 +475,13 @@ In the upcoming lessons you will:
475475
* [Add more metadata to your `pyproject.toml`](5-pyproject-toml.md) file to support PyPI publication.
476476
* [Learn how to build your package distribution](6-publish-pypi.md) files (**sdist** and **wheel**) and publish to **test PyPI**.
477477
* Finally you will learn how to publish to **conda-forge** from **PyPI**.
478+
479+
480+
## Footnotes
481+
482+
[^shell-lesson]: [Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)
483+
484+
[^python-modules]: [Python module docs](https://docs.python.org/3/tutorial/modules.html#packages)
485+
[^googledoc]:[Google docstring style](https://google.github.io/styleguide/pyguide.html)
486+
[^numpydoc]: [Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)
487+
[^epytextdoc]: [epydoc](https://epydoc.sourceforge.net/epytext.html)

0 commit comments

Comments
 (0)