Skip to content

Add documentation decision for package development #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jan-janssen wants to merge 1 commit into
base: main
Choose a base branch
from
+37 −0
Open

Add documentation decision for package development #22

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions decisions/26-003-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Documentation Website

## Status

Already implemented in:
- https://github.com/pyiron/atomistics
- https://github.com/pyiron/bagofholding
- https://github.com/pyiron/conda_subprocess
- https://github.com/pyiron/executorlib
- https://github.com/pyiron/flowrep/
- https://github.com/pyiron/lammpsparser
- https://github.com/pyiron/pyfileindex
- https://github.com/pyiron/pyiron_base
- https://github.com/pyiron/pyiron_core
- https://github.com/pyiron/pyiron_snippets
- https://github.com/pyiron/pyiron_workflow
- https://github.com/pyiron/pylammpsmpi
- https://github.com/pyiron/pysqa
- https://github.com/pyiron/structuretoolkit

## Context

Every package should have a short documentation website for new users to inform themselves about the functionality of the package before the release of version 1.0.

## Decision

To keep the barrier for creating the documentation low, the minimal documentation only consists of three parts:
- `README.md` - to give a general high level introduction to the package.
- `example.ipynb` - A jupyter notebook to demonstrate the functionality of the package. This jupyter notebook has three usecases:
- The jupyter notebook is rendered as a website to document the functionality of the package.
- The jupyter notebook is executed as integration test to validate that the documentation is compatible to the latest version of the package.
- The jupyter notebook can be tested live in interactive environments like mybinder to allow the users to test the software directly in their webbrowser.
- A rendered version of the docstrings for users to search for a specific function and understand how to use it,

## Consequences

While creating documentation in addition to inline docstrings is additional work, it hopefully helps to attract more users for the packages we develop as part of the pyiron organization.