Merge branch 'main' of github.com:SS-NES/meta-template

Author: manuGil

README.md

@@ -1,56 +1,65 @@
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-black.json)](https://github.com/copier-org/copier)
+# Meta-Template for Research Software
 
-# Research Software Meta Template
+A tool that helps **template creators** to create **software templates** for research software, and adopt best practices on sustainable software for Natural and Engineering Sciences. It provides a way to align best practices and reduce maintainance efforts across organisations, while allowing organisation to customize software templates to their needs. 
+
+If you came here looking for a template to start your own research software project, you check out the [Software Template Registry](REGISTRY.md) for a list of software templates that are using the *meta-template*.
+
+| [FAIR-Software Recommendations](https://fair-software.nl) | Badges|
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| 1. Code Repository | [![GitHub Badge](https://img.shields.io/github/v/release/SS-NES/meta-template?color=blue)](https://github.com/SS-NES/meta-template/releases/latest) |
+| 2. License |  [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) |
+| 3. Community Registry | [![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-black.json)](https://github.com/copier-org/copier)|
 
-A toolkit to start **software templates** for research software and adopt best practices on sustainable software for Natural and Engineering Sciences. It provides a way to align best practices and reduce maintainance efforts across 
-organisations, while allowing organisation to customize software templates to their needs. 
 
 ## Why?
 
-Because every organisation wants to produce high-quality research software by adopting common best practices, and we acknowledge that every organisation has practices and workflows that are only important to them. Therefore, we facilitate adopting common best practices for research software development through a highly customisable software template.
+Because research organisations can produce high-quality research software by adopting common best practices, and we acknowledge that every organisation has practices and workflows that are only important to them. Therefore, we facilitate the adopting  of common best practices for research software development through a highly customisable tool that allows organisations to create their own software templates, while aligning with the best practices of the Natural and Engineering Sciences community in the Netherlands.
 
 ## Features
 
 - Federation of best practices for research software project. Align with the best practice for research software development of the Natural and Engineering Science community in the Netherlands.
-- Reduce maintainabily. Enhancements to the meta-template can be incoorporated with ease in templating projects which reduces the time maintainers of templating projects have to spend in updating their templates.
+- Reduce maintainabily. Enhancements to the meta-template can be incoorporated with ease in templating projects which reduces the time *template creators* need to maintain and updater templating projects.
 - Flexibility. Generate templating projects for any programming languates and customize them for every use case.  
 - A curated list of open source licenses for your templating projects.
 
 ## Key Concepts
 
 - **Meta Template:** a template to start a software templating project. This repository. It contains common features that are shared among software templating projects. 
-- **Software Template:**  a template for research software projects generated using the *meta template*. It may contain custome features for a particular type of software project. For example, features specific to programming languages  (Python, R, Julia, etc.) or features specific to relevant use cases (Jupyter notebooks, organization A, organization B).
-- **Software Project:** the software schaffolding generated using a *software template*. It contains common features (from the *meta template*) and custom features (from its parent *software tempalte*).
+- **Software Template:**  a template for research software projects generated using the *meta template*. It may contain common and custom features for a particular type of software project. For example, features specific to programming languages  (Python, R, Julia, etc.) or features specific to relevant use cases (Jupyter notebooks, organization A, organization B).
+- **Software Project:** the software schaffolding generated using a *software template*. It contains files, directories and scaffolding code to start developing research software. 
+- **Template Creator:** a person or team that creates a *software template* using the *meta-template*. Template creators are responsible for maintaining the software template and keeping it up to date with the latest best practices provided by the **meta-template**.
+- **Template User:** a person or team that uses a *software template* to start a new  research software project. Template users decide when to update their research software projects with the latest best practices provided by a *software template*.
 
-## How to Use it
+## How to Create a Software Template
+To create a *software template* using the *meta-template*, you need to follow these steps:
 
 1. Install [Copier](https://copier.readthedocs.io) into your development environment.
 
-2. Start a new *software template*, rendered the latest version of this repository. This will generate boiler plate code that can be adopted for your particular uses case.
+2. Start a new *software template* by rendering the latest version of this repository. This will generate boiler plate code that can be adapted for your particular use case.
 
 ```shell
-copier copy https://github.com/SS-NES/meta-template.git <path/to/templating-project>
+copier copy gh:SS-NES/meta-template.git <path/to/templating-project>
 ```
 
-3. Make your *software template* a Git repository. Copier uses Git to version software tempaltes, therefore, a directory containing a *software template* must be a Git repository. 
+1. Make your *software template* a Git repository. Copier uses Git to track update, therefore, a directory containing a *software template* must be a Git repository. 
 
 ```shell
 cd <path/to/project-directory>
 git init
 git add . 
 git commit -m 'initial commit'
 ```
-4. Customize your template project. Consult the [Copier Documentation](https://copier.readthedocs.io/en/stable/creating/) and the [Jinja2 Documentation](https://jinja.palletsprojects.com/en/stable/templates/).
 
-5. To test if your software template is producing the results you want, your can render it into a *software project*. Use the `--vsc-ref HEAD` option to rendere all the changes you have made. 
+1. Customize your template project. Consult the [Copier Documentation](https://copier.readthedocs.io/en/stable/creating/) and the [Jinja2 Documentation](https://jinja.palletsprojects.com/en/stable/templates/).
+
+2. To test if your software template is producing the results you want, your can render it into a *software project*. Use the `--vsc-ref HEAD` option to rendere all the changes you have made. 
 
 ```shell
 # from a local Git repository
 copier copy --vcs-ref HEAD <path/to/your-software-template> <path/to/new-project/>
 
 # from a remote Git repository
-copier copy https://github.com/foo/<your-template>.git <path/to/new-project/>
+copier copy gh:foo/<your-template>.git <path/to/new-project/>
 ```
 
 > [!NOTE]
@@ -85,4 +94,8 @@ You can contribute to this initiative in two ways:
 
 ## Acknowledgements
 
-- This template was inspired by [Serious Scaffold Python](https://github.com/serious-scaffold/ss-python)
+This software was developed as part of the TDCC-NES Bottleneck Project "`Best
+Practices for Sustainable Software [SS-NES](https://tdcc.nl/projects/project-initiatives-nes/tdcc-nes-bottleneck-projects/best-practices-for-sustainable-software) funded by the Thematic Digital
+Competence Centre [TDCC](https://tdcc.nl/) for the Natural & Engineering Sciences [NES](https://tdcc.nl/about-tddc/nes).
+
+Some features in this software template were inspired by [Serious Scaffold Python](https://github.com/serious-scaffold/ss-python).

REGISTRY.md

@@ -6,7 +6,7 @@ A list of templating projects using the meta-template.
 
 | Template | Organisation |
 |----------|----------|
-| [Project name]()    | <Name>   |
+| [TU Delft FAIR Software Template](https://github.com/manuGil/fair-code)    | TU Delft DCC   |
 | [Project name]()    | <Name>   |
 | [Project name]()    | <Name>   |
 

copier.yml

@@ -34,3 +34,12 @@ description:
     help: A brief description of your template including its purpose, and for whom it is intended.
     default: My Template Description
 
+maintainer_info:
+    type: bool
+    help: Do you want to provide maintainer's information for this template?
+    default: Yes
+
+maintainer_email:
+    type: str
+    help: Email address of the maintainer of this template.
+    when: "{{ maintainer_info == true }}"

docs/_static/css/custom.css

@@ -0,0 +1,30 @@
+@import 'theme.css';
+
+.wy-side-nav-search .wy-dropdown>a,
+.wy-side-nav-search>a {
+    color:#343131;     
+}
+
+
+.wy-nav-top a {
+  color:#343131; 
+  font-weight:700
+}
+
+.wy-nav-top i {
+  font-size:30px;
+  color: #343131;
+  float:left;
+  cursor:pointer;
+  padding-top:inherit
+}
+
+img.logo {
+  display:block;
+  margin:0 auto;
+  height:auto;
+  width:60%;
+  border-radius:0;
+  max-width:100%;
+  background:transparent
+}

docs/_static/img/meta-logo.png

@@ -6,26 +6,32 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Meta Template'
+project = 'Meta-Template for Research Software'
 copyright = '2025, Manuel G. Garcia'
-author = 'Manuel G. Garcia'
+author = 'Manuel G. Garcia, Angelina Momin'
 release = '2.0.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     'sphinx_rtd_theme',
+    'sphinx_copybutton',
 ]
 
-
-
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
+github_url ='https://github.com/SS-NES/meta-template'
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ['_static']
+html_logo = "_static/img/meta-logo.png"
+html_style = 'css/custom.css'
+
+html_theme_options = {
+    'style_external_links': True,
+    'style_nav_header_background': '#f0f7fa',
+}

docs/conf.py

@@ -3,12 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Meta Template documentation
-===========================
+Meta-Template for Research Software
+=================================================
 
-Every organisation wants to produce high-quality research software by adopting common best practices, but we have to acknowledge that every organisation has practices and workflows that are only important to them. Therefore, we facilitate adopting common best practices for research software development through a highly customisable software template.
+A tool that helps **template creators** to create **software templates** for research software, and adopt best practices on sustainable software for Natural and Engineering Sciences. 
+It provides a way to align best practices and reduce maintainance efforts across organisations, while allowing organisation to customize software templates to their needs. 
 
-A template to initialize templating projects that comply with best practices on sustainable software in Natural and Engineering Science. This template containts boilerplate for developing custom research software templates using [copier](https://copier.readthedocs.io).
 
 .. toctree::
    :maxdepth: 2
@@ -17,14 +17,14 @@ A template to initialize templating projects that comply with best practices on
 
 .. toctree::
    :maxdepth: 2
-   :caption: TEMPLATES
+   :caption: Templating Documentation
 
    meta-template
    project-template
 
 .. toctree::
    :maxdepth: 2
-   :caption: USE CASES
+   :caption: Software Templates
 
    python-case
    notebook-case

docs/index.rst

@@ -1,5 +1,74 @@
-Meta Template
-==============
+The Meta-Template
+===================
+
+A tool that helps **template creators** to create **software templates** for research software and adopt best practices on sustainable software for Natural and Engineering Sciences. 
+It provides a way to align best practices and reduce maintenance efforts across organisations, while allowing organisation to customize software templates to their needs.
+
+Research organisations want to produce high-quality research software by adopting common best practices, 
+but we have to acknowledge that every organisation has practices and workflows that are only important to them. 
+Therefore, we facilitate adopting common best practices for research software development through a highly 
+customisable tool that allows organisations to create their own software templates, 
+while aligning with the best practices of the Natural and Engineering Sciences community in the Netherlands.
+
+The *meta-template* offers a tool for developing custom research software templates using `copier <https://copier.readthedocs.io>`_.
+*Software templates* generated using the *meta-template*  an easily aligh and comply with best practices on sustainable software in Natural and Engineering Science. 
+
+Features
+----------
+
+- Federation of best practices for research software project. Align with the best practice for research software development of the Natural and Engineering Science community in the Netherlands.
+- Reduce maintainabily. Enhancements to the meta-template can be incoorporated with ease in templating projects which reduces the time *template creators* need to maintain and updater templating projects.
+- Flexibility. Generate templating projects for any programming languates and customize them for every use case.  
+- A curated list of open source licenses for your templating projects.
+
+Key Concepts
+------------
+
+- **Best Practices:** a set of best practices for research software development in the Natural and Engineering Sciences. These best practices are defined by the community and are used to guide the development of high-quality research software projects.
+- **Meta Template:** a template to start a software templating project. This repository. It contains common features that are shared among software templating projects. 
+- **Software Template:**  a template for research software projects generated using the *meta template*. It may contain common and custom features for a particular type of software project. For example, features specific to programming languages  (Python, R, Julia, etc.) or features specific to relevant use cases (Jupyter notebooks, organization A, organization B).
+- **Software Project:** the software schaffolding generated using a *software template*. It contains files, directories and scaffolding code to start developing research software. 
+- **Template Creator:** a person or team that creates a *software template* using the *meta-template*. Template creators are responsible for maintaining the software template and keeping it up to date with the latest best practices provided by the **meta-template**.
+- **Template User:** a person or team that uses a *software template* to start a new  research software project. Template users decide when to update their research software projects with the latest best practices provided by a *software template*.
+
+
+Structure
+------------
+
+The *meta-template*  repository contians **common** and **custom** features for software templates. The common features are shared among all software templates and are used to generate the software scaffolding. The custom features are specific to a particular software template and are used to customize the software scaffolding for a particular use case (e.g. institution-specific). Template creators *adopt* common features from the meta-template, and *add* custom features to institution-specific software templates.
+
+.. code-block:: text
+
+    meta-template/
+    ├── meta
+    │   ├── common                          <- Common Questions/Options 
+    │   │   ├── citation.yml
+    │   │   ├── community.yml
+    │   │   ├── licensing.yml
+    │   │   ├── messages.yml
+    │   │   ├── settings.yaml
+    │   │   └── software.yml
+    │   ├── custom                          <- Institution-specific Questions/Options
+    │   │   └── customize.yml
+    │   ├── template                        <- Common templating elements
+    │   │   ├── includes
+    │   │   ├── tests
+    │   │   ├── README.md.jinja
+    │   │   ├── {{".gitignore.jinja"}}
+    │   │   ├── {{"{% if citation %}CITATION.cff{% endif %}.jinja"}}
+    │   │   ├── {{"{% if community %}CONTRIBUTING.md{% endif %}.jinja"}}
+    │   │   ├── {{"{{_copier_conf.answers_file}}.jinja"}}
+    │   │   ├── {{"CHANGELOG.md.jinja"}}
+    │   │   ├── {{"CODE_OF_CONDUCT.md.jinja"}}
+    │   │   └── {{"{% if software_license != 'No License' %}LICENSE{% endif %}.jinja"}}
+    │   ├── CONTRIBUTING.md.jinja
+    │   ├── README.md.jinja
+    │   ├── copier.yml.jinja
+    │   └── {{_copier_conf.answers_file}}.jinja
+    ├── LICENSE
+    ├── README.md
+    ├── REGISTRY.md
+    └── copier.yml                          <- Main copier configuration
+
 
-What is the meta template
 

docs/meta-template.rst

@@ -7,7 +7,7 @@ The Jupyter notebook template was generated using the meta template
 to streamline the adoption of best software development practices in the NES domain.
 
 By leveraging the meta template, essential files that help a project adhere to the FAIR principles, 
-such as license files, ``CODEOFCONDUCT.md``, ``README.md``, 
+such as license files, ``CODE_OF_CONDUCT.md``, ``README.md``, 
 and others were automatically included, eliminating the need for manual setup.
 
 This also improves maintainability as updates in the meta template, such as changes in license files, 
@@ -40,3 +40,34 @@ the following modifications were made:
 - ``tests/`` folder – Organizes and runs validation tests on code or data processing steps.
 
 This ensures a structured, reproducible, and well-documented environment for research software development.
+
+
+
+How to Use
+----------------
+Your can quickly use this template as follows:
+
+.. code-block:: bash
+
+   # Create a new project using the fair-code template
+   copier copy gh:SS-NES/notebook-template.git <my-software-project>
+
+   # Navigate to the project directory
+   cd <my-software-project>
+
+   # initialize a git repository
+   git init
+   git add .
+   git commit -m "Initial commit of my software project"
+
+   # start coding!
+
+.. note::
+
+   This software template can be applied to preexisting research software projects using the `copier copy` command.
+
+   .. code-block:: bash
+      
+      copier copy gh:SS-NES/notebook-template.git <./your-preexisting-project>
+
+