euroargodev / euroargodev/software_guidelines

The software documentation is hosted on the web

Open
#48 0 comments 0 reactions 0 assignees View on GitHub
guideline
Dominant language
Python
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

This a guideline that follows from the early stage of the documentation, once the README file (#36) and/or the codebase becomes too large.

The software documentation, whatever the format (eg: pdf, markdown, etc...) must be hosted and accessible on the web.

In practice, it is recommended to use a webpages generating system to host a documentation online. This is fairly easy to implement since many online services can directly be plugged onto a git-based repository content.

Such online documentation systems are, for instance:
- [Read The Docs](https://about.readthedocs.com/) (free for open-source project),
- [Github Pages](https://docs.github.com/en/pages).

These services can be used to publish online a documentation that is possibly generated from static files located in a dedicated folder of the software repository.

Such documentation (based on static files like markdown or rst) can be generated with, for instance:
- [Sphynx](https://www.sphinx-doc.org/en/master/),
- [Mkdocs](https://www.mkdocs.org/),
- [Jupyter Books](https://jupyter-book.readthedocs.io/v1/intro.html).

💡 Euroargodev provides a [repository template for a documentation](https://github.com/euroargodev/online_documentation) that can be used to quickly start your own online documentation.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.