From 80d7282ca0377a94cad67a65215a00ae63ae9437 Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Mon, 2 Oct 2023 18:52:25 +0200 Subject: [PATCH] use markdown for the index file for more consistency --- content/index.md | 77 +++++++++++++++++++++++++++++++++++++++++++++ content/index.rst | 80 ----------------------------------------------- 2 files changed, 77 insertions(+), 80 deletions(-) create mode 100644 content/index.md delete mode 100644 content/index.rst diff --git a/content/index.md b/content/index.md new file mode 100644 index 0000000..916977a --- /dev/null +++ b/content/index.md @@ -0,0 +1,77 @@ +# How to document your research software + +In this lesson we will discuss different solutions for implementing and +deploying code documentation. + +We will start with a discussion about **what makes a good README**. For many +projects, a README is more than enough. + +We will then learn how to build documentation with the +**documentation generator** [Sphinx](https://www.sphinx-doc.org) (and compare it +with others) and how to +deploy it to [Read the Docs](https://readthedocs.org), a service which hosts +open documentation for free. + +This demonstration will be **independent of programming languages**. + +We will also learn how +to deploy a **project website or personal homepage** to [GitHub Pages](https://pages.github.com). +The approach that we will learn will be transferable to +[GitLab Pages](https://about.gitlab.com/features/pages/) and +[Bitbucket Pages](https://pages.bitbucket.io). + +```{prereq} +1. Basic understanding of Git. + +2. For the Sphinx part, You need to have + [sphinx](https://www.sphinx-doc.org) and [sphinx_rtd_theme](https://sphinx-rtd-theme.readthedocs.io/) installed + (they are part of the [coderefinery environment](https://coderefinery.github.io/installation/conda-environment/)). + +3. For the [GitHub Pages](https://pages.github.com) part you need a [GitHub](https://github.com) account. +``` + +```{csv-table} +:widths: auto +:delim: ; + +10 min ; {doc}`wishlist` +10 min ; {doc}`tools` +20 min ; {doc}`in-code-documentation` +30 min ; {doc}`writing-readme-files` +30 min ; {doc}`sphinx` +20 min ; {doc}`gh_workflow` +20 min ; {doc}`gh-pages` +5 min ; {doc}`summary` +``` + +```{toctree} +:maxdepth: 1 +:caption: The lesson + +wishlist.md +tools.md +in-code-documentation.md +writing-readme-files.md +sphinx.md +gh_workflow.md +gh-pages.md +summary.md +``` + +```{toctree} +:maxdepth: 1 +:caption: Reference + +exercises.md +guide.md +license.md +``` + +```{toctree} +:maxdepth: 1 +:caption: About + +All lessons +CodeRefinery +Reusing +``` diff --git a/content/index.rst b/content/index.rst deleted file mode 100644 index 4be8afe..0000000 --- a/content/index.rst +++ /dev/null @@ -1,80 +0,0 @@ -How to document your research software -====================================== - -In this lesson we will discuss different solutions for implementing and -deploying code documentation. - -We will start with a discussion about **what makes a good README**. For many -projects, a README is more than enough. - -We will then learn how to build documentation with the -**documentation generator** `Sphinx `__ (and compare it -with others) and how to -deploy it to `Read the Docs `__, a service which hosts -open documentation for free. - -This demonstration will be **independent of programming languages**. - -We will also learn how -to deploy a **project website or personal homepage** to `GitHub Pages `__. -The approach that we will learn will be transferable to -`GitLab Pages `__ and -`Bitbucket Pages `__. - - -.. prereq:: - - 1. Basic understanding of Git. - - 2. For the Sphinx part, You need to have `sphinx - `__ and `sphinx_rtd_theme - `__ installed (they are part of - the `coderefinery environment `__). - - 3. For the `GitHub Pages `__ part you need a `GitHub `__ account. - - -.. csv-table:: - :widths: auto - :delim: ; - - 10 min ; :doc:`wishlist` - 10 min ; :doc:`tools` - 20 min ; :doc:`in-code-documentation` - 30 min ; :doc:`writing-readme-files` - 30 min ; :doc:`sphinx` - 20 min ; :doc:`gh_workflow` - 20 min ; :doc:`gh-pages` - 5 min ; :doc:`summary` - - -.. toctree:: - :maxdepth: 1 - :caption: The lesson - - wishlist.md - tools.md - in-code-documentation.md - writing-readme-files.md - sphinx.md - gh_workflow.md - gh-pages.md - summary.md - - -.. toctree:: - :maxdepth: 1 - :caption: Reference - - exercises - guide - license - - -.. toctree:: - :maxdepth: 1 - :caption: About - - All lessons - CodeRefinery - Reusing