documentation_example
Repository used for documentation talk at the Best practice guide for software developers and scientists in Extremes DT and Climate DT workshop - June 2023
Science Score: 44.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
✓CITATION.cff file
Found CITATION.cff file -
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
○Academic publication links
-
○Committers with academic emails
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (15.6%) to scientific vocabulary
Repository
Repository used for documentation talk at the Best practice guide for software developers and scientists in Extremes DT and Climate DT workshop - June 2023
Basic Info
- Host: GitHub
- Owner: samumantha
- License: cc-by-4.0
- Default Branch: main
- Homepage: https://samumantha.github.io/documentation_example/
- Size: 2.79 MB
Statistics
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
- Releases: 1
Metadata Files
Readme.md
Documenting code
Materials for workshop on "Best practice guide for software developers and scientists in Extremes DT and Climate DT" in June 2023
Samantha Wittke, CSC - IT center for science, CodeRefinery
❓ Why?
- You will probably use your code in the future and may forget details.
- You may want others to use your code (almost impossible without documentation).
- You may want others to contribute to the code.
- Shield your limited time and let the documentation answer FAQs.
🗒️ Common parts
A checklist, if you want :)
- Purpose
- Authors
- License
- Recommended citation
- Copy-paste-able example to get started
- Dependencies and their versions or version ranges
- Installation instructions
- Tutorials covering key functionality
- Reference documentation (e.g. API) covering all functionality
- How do you want to be asked questions (mailing list or forum or chat or issue tracker)
- Possibly a FAQ section
- Contribution guide
🧐 In-code
Comments
Describing why this piece of code is there, i.e. its purpose.
Comments that can be replaced by version control: - keeping zombie code
```
Do not run this code!:
if temperature > 0:
print('It is warm')
```
- documenting version
```
removed on August 5
if() ...
Now it connects to the API with o-auth2, updated 05/05/2016
```
➕ : close to code, ➖: too close to code
Docstrings
``` def my_function(argument): """Summary or description of the function
Parameters:
argument (int): Description of argument
Returns:
int: Description of return value
"""
return argument
print(somefunction.doc_) ```
Good docstrings describe: * What the function does * What goes in (including the type of the input variables) * What goes out (including the return type)
Good variable/function naming is documentation!
❗ README
... usually the first thing someone visiting your repository sees -> First impression!
A minimal README should include:
- A descriptive project title
- Motivation (why the project exists) and basics
- Installation / How to setup
- Copy-pastable quick start code example
- Usage reference (if not elsewhere)
- Recommended citation if someone uses it
- Other related tools (“see also”)
often a README is enough!
🤓 External documentation
...When README is not enough...
Static site generators build websites out of plain text files (often .md or .rst).
Docstrings can automatically be integrated into documentation, no need to write this twice!
Tools
- Sphinx, for a quick start
- Zola, all CodeRefinery lesson pages are build with that
- Jekyll, integrated with Github
- Many more
Sphinx
Sphinx + GithubPages + Github actions
🏡 Take home messages
I hope you latest now * Understand the importance of writing code documentation together with the source code * Know what makes a good documentation * Know what tools can be used for writing documentation * Are able to motivate a balanced decision: sometimes READMEs are absolutely enough
🐹 References and Resources
This material is based on CodeRefinery Documentation lesson: https://coderefinery.github.io/documentation/ and licensed under CC BY 4.0
Owner
- Name: Samantha Wittke
- Login: samumantha
- Kind: user
- Location: Helsinki, Finland
- Company: Finnish Geospatial Research Institute and Aalto University
- Repositories: 3
- Profile: https://github.com/samumantha
Doctoral student at Aalto University and Researcher at Finnish Geospatial Research Institute Remote Sensing, GIS, Python, Machine Learning
Citation (CITATION.cff)
cff-version: 1.2.0
message: "If you use this example, please cite it as below."
authors:
- family-names: Wittke
given-names: Samantha
orcid: https://orcid.org/0000-0002-9625-7235
title: "Software documentation example"
version: 1.0
doi: xx/xx
date-released: 2023-06-16
GitHub Events
Total
Last Year
Committers
Last synced: over 1 year ago
Top Committers
| Name | Commits | |
|---|---|---|
| Samantha Wittke | 3****a | 14 |
| Samantha Wittke | s****t@o****i | 1 |
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 10 months ago
All Time
- Total issues: 0
- Total pull requests: 0
- Average time to close issues: N/A
- Average time to close pull requests: N/A
- Total issue authors: 0
- Total pull request authors: 0
- Average comments per issue: 0
- Average comments per pull request: 0
- Merged pull requests: 0
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 0
- Pull requests: 0
- Average time to close issues: N/A
- Average time to close pull requests: N/A
- Issue authors: 0
- Pull request authors: 0
- Average comments per issue: 0
- Average comments per pull request: 0
- Merged pull requests: 0
- Bot issues: 0
- Bot pull requests: 0