Merge pull request #20 from fairdataihub/updated-docs

refactor: ♻️ Documentation for Codefair v2

docs/.vitepress/config.js

@@ -127,6 +127,7 @@ export default withMermaid(
   }),
 );
 
+// Developer Guide Sidebar
 function appSidebarGuide() {
   return [
     {
@@ -148,13 +149,15 @@ function appSidebarGuide() {
   ];
 }
 
+// User guide sidebarq
 function portalSidebarGuide() {
   return [
     {
       text: 'Getting Started',
       collapsible: true,
       items: [
         { text: 'Introduction', link: '/docs/intro.md' },
+        { text: 'About Codefair', link: '/docs/about.md' },
         { text: 'Installation', link: '/docs/installation.md' },
       ],
     },
@@ -163,8 +166,11 @@ function portalSidebarGuide() {
       collapsible: true,
       items: [
         { text: 'GitHub Issue Dashboard', link: '/docs/dashboard.md' },
+        { text: 'UI Dashboard', link: '/docs/ui-dashboard.md' },
+        { text: 'Overview of Features', link: '/docs/features.md' },
         { text: 'LICENSE', link: '/docs/license.md' },
         { text: 'Metadata', link: '/docs/metadata.md' },
+        { text: 'CWL Validation', link: '/docs/cwl.md' },
       ],
     },
     {

docs/docs/about.md

@@ -0,0 +1,24 @@
+---
+lang: en-US
+title: About Codefair
+description: Overview of Codefair
+head:
+  - - meta
+    - name: og:image
+      content: https://kalai.fairdataihub.org/api/generate?title=Codefair%20Documentation&description=About%20Codefair&app=codefair&org=fairdataihub
+---
+
+# :sparkles: About Codefair
+
+Codefair is a free and open source GitHub app that acts as your personal assistant when it comes to making your research software reusable and especially complying with the Findable, Accessible, Interoperable, Reusable (FAIR) Principles for Research Software (FAIR4RS Principles).
+
+<!-- ![dashboard](/dashboard.png){width=10%}
+![metadata-editor](/metadata-ui.png){width=10%} -->
+
+## How does Codefair work?
+
+Simply install Codefair from the GitHub marketplace on your software's GitHub repository. By communicating with you through GitHub issues and submitting pull requests, Codefair will ensure that your software follows best coding practices, provides metadata in standard formats, includes a license file, is archived on Zenodo, and much more to align with the FAIR4RS principles.
+
+## Who should use Codefair?
+
+Currently, Codefair helps make software FAIR by following the FAIR Biomedical Research Software (FAIR-BioRS) guidelines. Therefore, it is designed mainly for biomedical research software. However, most of the steps in the FAIR-BioRS guidelines are applicable to any research software, regardless of the field. This means that anyone developing research software can use Codefair. Whether you are developing artificial intelligence (AI)/machine learning (ML) models with Python, data visualization tools with Jupyter Notebook, or data analysis code with R, Codefair is here to assist you.

docs/docs/cwl.md

@@ -0,0 +1,31 @@
+---
+lang: en-US
+title: CWL Validation
+description: Overview of the CWL Validation Feature
+head:
+  - - meta
+    - name: og:image
+      content: https://kalai.fairdataihub.org/api/generate?title=Codefair%20Documentation&description=CWL%20Validation&app=codefair&org=fairdataihub
+---
+
+# :sparkles: CWL Validation
+
+This section provides an overview of the CWL Validation feature of Codefair.
+
+## What is CWL Validation?
+
+The Common Workflow Language (CWL) is a specification for describing analysis workflows and tools in a way that makes them portable and scalable across a variety of software and hardware environments, from workstations to cluster, cloud, and high-performance computing (HPC) environments. The CWL standard is designed to meet the needs of data-intensive science, such as Bioinformatics, Medical Imaging, Astronomy, Physics, and Chemistry. CWL is developed by the [Common Workflow Language working group](https://www.commonwl.org/).
+
+The CWL Validation feature of Codefair will check if the CWL files in a repository are compliant with the CWL standard. The feature will automatically detect CWL files in a repository and submit a pull request with a GitHub action configuration file that includes workflows for checking the syntax and structure of the CWL files. The action will check CWL files on every commit and submit a pull request to address any syntax or structure issue. The feature will make use of existing tools such as [cwltool](https://cwltool.readthedocs.io/en/stable/) and [CWL command line validator](https://cwltool.readthedocs.io/en/stable/cli.html#cmdoption-cwltool-validate).
+
+## CWL Issue Dashboard
+
+The CWL Section on the GitHub issue dashboard will display the CWL validations of the repository. The dashboard will show the status of the CWL validation and provide a link to the view the details of the validation results.
+
+![CWL Issue Dashboard](/cwl-dashboard.png)
+
+## CWL Validation Results
+
+The CWL validation results page will display the details of the CWL validation. The page will show the status of the validation, the list of CWL files checked, and the details of the issues found in the CWL files. The page will also provide a link to the pull request created to address the issues found in the CWL files.
+
+![CWL Validation Results](/cwl-results-ui.png)

docs/docs/dashboard.md

@@ -12,8 +12,8 @@ head:
 
 As soon as you install the Codefair app, it opens a GitHub issue in your repository. This issue contains a dashboard that provides a point by point overview of your software's compliance with elements that make a software FAIR. The dashboard is updated with each new commit to the main branch. A check mark is shown next to elements your software is complying with (e.g., the dashboard in screenshot below shows that the software has a LICENSE file). A red cross is shown next to the elements that are not complied with yet (e.g., the dashboard in screenshot below shows that the software does not have required metadata files). For such elements, there is a button that takes you to the Codefair website where you can easily address the compliance issue through a convenience user interface.
 
-::: info
-Keep the issue open as making and keeping software FAIR is a continuous process that evolves along with the software.
+::: warning
+If you close the issue, Codefair will deactivate until you reopen the issue but if you delete the issue, you will need to reinstall Codefair to that repository.
 :::
 
 ![GitHub Issue Dashboard](/dashboard-metadata.png)

docs/docs/features.md

@@ -0,0 +1,24 @@
+---
+lang: en-US
+title: Overview of Features
+description: Overview of Features
+head:
+  - - meta
+    - name: og:image
+      content: https://kalai.fairdataihub.org/api/generate?title=Codefair%20Documentation&description=Overview%20of%20Features&app=codefair&org=fairdataihub
+---
+
+# :sparkles: Overview of Features
+
+The table below lists all the current and upcoming features of Codefair. It also indicates for what type of research software each feature is suitable.
+
+Specifically the `Research discipline` column indicates the research discipline of the software for which this feature is suitable (e.g., biomedical, mathematics, etc.). Similarly, the `Coding language` column indicates the coding language of the research software for which this feature is suitable (e.g., Python, R, etc.). The `Software format` column indicates the format of the research software for which this feature is suitable (e.g., desktop software, command line interface, etc.). Finally, the `Software application` indicates the application of the research software for which the feature is suitable (e.g., computational model, AI-ML model, etc.).
+
+| Feature                                                                  | Anticipated release date | Research discipline | Coding language                | Software format        | Software application |
+| :----------------------------------------------------------------------- | :----------------------- | :------------------ | :----------------------------- | :--------------------- | :------------------- |
+| [License](./license.md)                                                  | Released                 | All                 | All                            | All                    | All                  |
+| [Metadata](./metadata.md)                                                | Released                 | All                 | All                            | All                    | All                  |
+| [CWL validation](./cwl.md)                                               | August 2024              | All                 | Common Workflow Language (CWL) | Command line interface | All                  |
+| [Quick release and archiving](./upcoming.md#quick-release-and-archiving) | October 2024             | All                 | All                            | All                    | All                  |
+| [Code formatter](./upcoming.md#code-formatter)                           | TBD                      | All                 | Python, Javascript, Typescript | All                    | All                  |
+| [Automated CHANGELOG update](./upcoming.md#automated-changelog-update)   | TBD                      | All                 | All                            | All                    | All                  |

docs/docs/ui-dashboard.md

@@ -0,0 +1,26 @@
+---
+lang: en-US
+title: UI Dashboard
+description: Understanding the UI Dashboard
+head:
+  - - meta
+    - name: og:image
+      content: https://kalai.fairdataihub.org/api/generate?title=Codefair%20Documentation&description=Understanding%20the%20UI%20Dashboard&app=codefair&org=fairdataihub
+---
+
+# :sparkles: Dashboard Overview
+
+The UI dashboard shows a list of all the repositories that have installed the Codefair app. The dashboard provides a way to manage the FAIR compliance of the repositories. The dashboard is updated with each new commit to the main branch of the repositories.
+
+![ui-dashboard](/ui-dashboard.png)
+
+# :card_file_box: Repository Selected
+
+When you select a repository from the list, the dashboard will show the FAIR compliance of the selected repository. The dashboard will display a list of elements that make a software FAIR. A check mark is shown next to elements the software is complying with.
+
+- View the repository on GitHub
+- Rerun all Codefair checks
+- Rerun CWL Validation
+- View Codefair settings
+
+![repository-selected](/repo-dashboard.png)