[TOC]
[!NOTE]
This is the README.md file of the ENCORE template and is provided to give some background information about the project organization and to provide pointers to further information.
Version: V.4.x (main branch). Use this development template for new projects)
Previous ENCORE versions are found as separate branches starting from V4.1.1
ENCORE
Further information about ENCORE is also found in the ENCORE wiki. To facilitate further discussion about the develop of ENCORE we have set up Discussions.
The standardized File System Structure (sFSS) / Project Compendium
To organize a computational project into a project compendium, ENCORE has defined a sFSS which is a predefined but flexible directory structure to organize conceptual information, data, code, documentation, and (intermediate) results (e.g., tables, figures, text files). Each directory of the sFSS contains one or more predefined files to provide explanation and guidance for documentation. The sFSS is also referred to as a Project Compendium.
Markdown
The Markdown files (*.md) in the sFSS can be edited with any text editor but to show the markup one should use a Markdown viewer such as Typora (www.typora.io; Windows, Mac) or Notepad++ (Windows; install the MarkdownViewer plugin).
Project Team and Compendium Recipient
The (leader of the) Project Team is responsible for the organization and documentation of the project. The Step-by-Step ENCORE Guide and the explanation/instructions in the various README and other files are intended for the Project Team.
The Compendium Recipient is, for example, a direct colleague, a peer, or a reviewer who wants to inspect and/or reproduce the results of a project. Or it can be an archive such as Zenodo.
Start to explore the project by opening Navigate.html in your browser.
Content of sFSS root directory
Directories
ENCORE AUTOMATION
The GitHub repository ENCORE_AUTOMATION provides scripts to automate specific ENCORE tasks. Currently, the automatic creation of a local ENCORE project and and project repository on GitHub.com
ENCORE SUPPLEMENT
The GitHub repository ENCORE_SUPPLEMENT provides supplementary information to ENCORE such as documentation, manuscripts, and figures.
Sharing with a Compendium Recipient
Notes
Content of sFSS root directory
The following files need to be updated by the project owner
0_PROJECT.md. Short description of project, contact person, and project team
0_GETTINGSTARTED.txt. Template document (plain text format). Copy this file to your favourite editor to add content.
Examples:
0_GETTINGSTARTED.docx. Template document (Microsoft Word format to show how to include links). The DOCX file can be saved as HTML (make sure you use utf-8 encoding).
0_GETTINGSTARTED.tex. Template document (LaTex format to show how to include links). The LaTex file can be converted to HTML with Pandoc.
0_GETTINGSTARTED.html. Example of exported HTML file used by the FSS navigator.
User documentation
General
README.md. This file.
2_CITATION.md. How to cite ENCORE and the FSS Navigator.
3_LICENSE.md. License associated with the ENCORE template
.FSSignore. Currently not used.
Compendium (sFSS) Navigator
The Compendium Navigator is a Python program that generates Navigate.html when executed. This html file can be opened in a web-browser and guides the user to the most important parts of a projects.
Compendium Navigator files:
Navigate.html. Open in your browser to navigate the standardized file system.
Navigate.py. Standalone Python 3 script to generate Navigate.html to navigate the sFSS. Can be run from the command line (Navigate.py -h).
Navigate_U.sh. Shell script to run Navigate on Unix/Linux systems. Change the first line (#!/usr/bin/Python) if necessary. Make executable using chmod +x
There are also executables available for Windows and Mac OS. These are available from the GitHub release and also from Zenodo (DOI: https://doi.org/10.5281/zenodo.7985655):
Test_Navigate_Module.py. Python script to show how to use Navigate.py as module in other Python scripts. This may help to keep Navigate.html up-to-date without manually executing Navigate.py.
Navigation.conf. Configuration file for the FSS Navigator.
Directories