diff --git a/.github/workflows/code-style.yml b/.github/workflows/code-style.yml index a953b82..87b72a8 100644 --- a/.github/workflows/code-style.yml +++ b/.github/workflows/code-style.yml @@ -44,3 +44,41 @@ jobs: run: | flake8 docs --count --select=E9,F63,F7,F82 --show-source --statistics flake8 docs --count --max-complexity=12 --max-line-length=130 --statistics + + file-naming: + name: File Naming Convention + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Check docs file naming + run: | + echo "Checking documentation filenames…" + + invalid_files=$(find docs \ + -type f \( \ + -name "*.rst" \ + -o -name "*.png" \ + -o -name "*.jpg" \ + -o -name "*.jpeg" \ + -o -name "*.svg" \ + -o -name "*.gif" \ + -o -name "*.tiff" \ + \) \ + | grep -Ev '^docs/_(static|templates)/' \ + | grep -E '[A-Z_]' || true) + + if [ -n "$invalid_files" ]; then + echo "❌ Invalid documentation filenames found:" + echo "$invalid_files" + echo "" + echo "Rules:" + echo " - lowercase only" + echo " - use '-' as separator" + echo " - no underscores '_'" + echo " - exception: docs/_static/** and docs/_templates/**" + exit 1 + fi + + echo "✅ Documentation filenames look good." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6c3e76..a881f20 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,18 @@ If you find a bug in the documentation, please [open an issue](https://github.co The documentation is hosted on Read-the-Docs and using standard Sphinx documentation. The documentation is written in reStructuredText (`.rst`) format. It can be compiled locally using Sphinx and viewed in a web browser. +### File Naming Convention + +While it may not be clear at first, naming of documentation files is important for clarity and organization. It is also directly reflected in the URLs of the hosted documentation. Please follow these conventions when naming documentation files: + +- Use lowercase letters. +- Use hyphens (`-`) to separate words. Do not use underscores (`_`). +- Avoid using special characters or spaces. +- Use descriptive names that reflect the content of the file. +- Do not change names of existing files unless absolutely necessary, as this may break links. + +Adhering to these conventions will help maintain a consistent and organized documentation structure. + ### Writing Style When contributing to the documentation, please follow the following writing style: diff --git a/docs/architecture/dmp_if.rst b/docs/architecture/dmp-if.rst similarity index 100% rename from docs/architecture/dmp_if.rst rename to docs/architecture/dmp-if.rst diff --git a/docs/architecture/fair_if.rst b/docs/architecture/fair-if.rst similarity index 100% rename from docs/architecture/fair_if.rst rename to docs/architecture/fair-if.rst diff --git a/docs/architecture/intro.rst b/docs/architecture/intro.rst index be48eb3..8eb0b68 100644 --- a/docs/architecture/intro.rst +++ b/docs/architecture/intro.rst @@ -11,7 +11,7 @@ A key objective of this architecture is to prevent vendor lock-in, ensuring tool The architecture also supports both current well-known and potential future patterns of interactions between components, fostering innovative use cases that enhance automation and machine-actionability of digital object information exchange. For example, while it is yet uncommon for data repositories to update DMPs, the architecture anticipates and accommodates such potential pathways. -.. figure:: OSTrails-architecture.png +.. figure:: ostrails-architecture.png OSTrails Architecture diff --git a/docs/architecture/OSTrails-architecture.png b/docs/architecture/ostrails-architecture.png similarity index 100% rename from docs/architecture/OSTrails-architecture.png rename to docs/architecture/ostrails-architecture.png diff --git a/docs/architecture/skg_if.rst b/docs/architecture/skg-if.rst similarity index 100% rename from docs/architecture/skg_if.rst rename to docs/architecture/skg-if.rst diff --git a/docs/commons/dmp/dmp-common-standard-diagram.png b/docs/commons/dmp/dmp-common-standard-diagram.png new file mode 100644 index 0000000..bb8fd46 Binary files /dev/null and b/docs/commons/dmp/dmp-common-standard-diagram.png differ diff --git a/docs/commons/dmp/dmp-common-standard.rst b/docs/commons/dmp/dmp-common-standard.rst index a85601b..46ce16a 100644 --- a/docs/commons/dmp/dmp-common-standard.rst +++ b/docs/commons/dmp/dmp-common-standard.rst @@ -30,7 +30,7 @@ Within the DMP Commons, the RDA DMP Common Standard: The standard intentionally avoids domain-specific requirements or policy-driven constraints. Such specializations are addressed at higher layers (e.g. application profiles), allowing the common standard to remain stable and broadly applicable. -.. figure:: https://raw.githubusercontent.com/RDA-DMP-Common/RDA-DMP-Common-Standard/refs/tags/v1.2/docs/diagrams/maDMP-diagram.png +.. figure:: dmp-common-standard-diagram.png :alt: RDA DMP Common Standard for maDMPs v1.2 :target: https://github.com/RDA-DMP-Common/RDA-DMP-Common-Standard/tree/v1.2 diff --git a/docs/commons/dmp/dmp-commons.rst b/docs/commons/dmp/dmp-commons.rst index c52ae03..11e9793 100644 --- a/docs/commons/dmp/dmp-commons.rst +++ b/docs/commons/dmp/dmp-commons.rst @@ -16,7 +16,7 @@ In addition, DMP Commons are relevant for data stewards and other stakeholders w The Commons are built as a **layered framework** consisting of a common data model, an OSTrails (i.e. Europe/EOSC) -specific application profile, and a standard API. Together, these layers enable consistent interpretation of DMP content and predictable interactions between services, regardless of their internal architectures. This approach allows platforms to evolve independently while remaining interoperable at the boundaries. In addition, we provide `maDMP mappings `_ to support the development of application profiles and to align DMP information with external standards and domain models. -.. figure:: ostrails_dmp-commons.png +.. figure:: ostrails-dmp-commons.png :alt: DMP Commons Layers :align: center :scale: 60% diff --git "a/docs/commons/dmp/mappings/Austrian-FWF\342\200\223maDMP-mapping.rst" b/docs/commons/dmp/mappings/austrian-fwf-madmp.rst similarity index 100% rename from "docs/commons/dmp/mappings/Austrian-FWF\342\200\223maDMP-mapping.rst" rename to docs/commons/dmp/mappings/austrian-fwf-madmp.rst diff --git a/docs/commons/dmp/mappings/index.rst b/docs/commons/dmp/mappings/index.rst index 78472fe..f2382c2 100644 --- a/docs/commons/dmp/mappings/index.rst +++ b/docs/commons/dmp/mappings/index.rst @@ -73,5 +73,5 @@ We will add more mappings as we progress with the review. :maxdepth: 1 :titlesonly: - Science Europe maDMP mapping - Austrian FWF – maDMP mapping + Science Europe maDMP mapping + Austrian FWF – maDMP mapping diff --git a/docs/commons/dmp/mappings/Science-Europe-maDMP-mapping.rst b/docs/commons/dmp/mappings/science-europe-madmp.rst similarity index 100% rename from docs/commons/dmp/mappings/Science-Europe-maDMP-mapping.rst rename to docs/commons/dmp/mappings/science-europe-madmp.rst diff --git a/docs/commons/dmp/ostrails_dmp-commons.png b/docs/commons/dmp/ostrails-dmp-commons.png similarity index 100% rename from docs/commons/dmp/ostrails_dmp-commons.png rename to docs/commons/dmp/ostrails-dmp-commons.png diff --git a/docs/commons/dmp/ostrails_dmp-commons.svg b/docs/commons/dmp/ostrails-dmp-commons.svg similarity index 100% rename from docs/commons/dmp/ostrails_dmp-commons.svg rename to docs/commons/dmp/ostrails-dmp-commons.svg diff --git a/docs/commons/FAIR/Assessment-Recommended-API.rst b/docs/commons/fair/assessment-recommended-api.rst similarity index 100% rename from docs/commons/FAIR/Assessment-Recommended-API.rst rename to docs/commons/fair/assessment-recommended-api.rst diff --git a/docs/commons/FAIR/Catalogue-of-Benchmark-Scoring-Algorithms.rst b/docs/commons/fair/catalogue-of-benchmark-scoring-algorithms.rst similarity index 100% rename from docs/commons/FAIR/Catalogue-of-Benchmark-Scoring-Algorithms.rst rename to docs/commons/fair/catalogue-of-benchmark-scoring-algorithms.rst diff --git a/docs/commons/FAIR/Catalogue-of-Benchmarks.rst b/docs/commons/fair/catalogue-of-benchmarks.rst similarity index 100% rename from docs/commons/FAIR/Catalogue-of-Benchmarks.rst rename to docs/commons/fair/catalogue-of-benchmarks.rst diff --git a/docs/commons/FAIR/Catalogue-of-Tests.rst b/docs/commons/fair/catalogue-of-tests.rst similarity index 98% rename from docs/commons/FAIR/Catalogue-of-Tests.rst rename to docs/commons/fair/catalogue-of-tests.rst index 4bf8811..90ede9a 100644 --- a/docs/commons/FAIR/Catalogue-of-Tests.rst +++ b/docs/commons/fair/catalogue-of-tests.rst @@ -13,7 +13,7 @@ This repository is built on top of the **FAIR Data Point (FDP)**, a software framework maintained by the `FAIRDataTeam `_. -.. figure:: Test-Algorithm-Registry.png +.. figure:: test-algorithm-registry.png :alt: Test Algorithm Registry :align: center diff --git a/docs/commons/FAIR/FAIR-commons.rst b/docs/commons/fair/fair-commons.rst similarity index 67% rename from docs/commons/FAIR/FAIR-commons.rst rename to docs/commons/fair/fair-commons.rst index c630d97..c5e03f7 100644 --- a/docs/commons/FAIR/FAIR-commons.rst +++ b/docs/commons/fair/fair-commons.rst @@ -13,11 +13,11 @@ The following resources in this section are part of the FAIR Commons component. :maxdepth: 1 :titlesonly: - Guidance Element Specification - FAIR Test Results Vocabulary (FTR) - Assessment Recommended API - Catalogue of Benchmarks and Metrics - Catalogue of Tests - Catalogue of Benchmark Scoring Algorithms - Code of Shared Tests + Guidance Element Specification + FAIR Test Results Vocabulary (FTR) + Assessment Recommended API + Catalogue of Benchmarks and Metrics + Catalogue of Tests + Catalogue of Benchmark Scoring Algorithms + Code of Shared Tests diff --git a/docs/commons/fair/fair-test-results-diagram-v12.png b/docs/commons/fair/fair-test-results-diagram-v12.png new file mode 100644 index 0000000..58725f0 Binary files /dev/null and b/docs/commons/fair/fair-test-results-diagram-v12.png differ diff --git a/docs/commons/FAIR/FAIR-Test-Results-Vocabulary-FTR.rst b/docs/commons/fair/fair-test-results-vocabulary-ftr.rst similarity index 94% rename from docs/commons/FAIR/FAIR-Test-Results-Vocabulary-FTR.rst rename to docs/commons/fair/fair-test-results-vocabulary-ftr.rst index 91b83f5..bf31f8e 100644 --- a/docs/commons/FAIR/FAIR-Test-Results-Vocabulary-FTR.rst +++ b/docs/commons/fair/fair-test-results-vocabulary-ftr.rst @@ -32,8 +32,9 @@ of this activity is either a ``TestResult`` or a ``TestResultSet``. ---- -.. image:: https://github.com/OSTrails/FAIR_testing_resource_vocabulary/blob/main/development/img/FAIRTestResult_diagram_v12.drawio.png?raw=true - :align: center +.. figure:: fair-test-results-diagram-v12.png + :alt: FAIR Testing Resource Vocabulary (FTR) + :target: https://github.com/OSTrails/FAIR_testing_resource_vocabulary Specification diff --git a/docs/commons/FAIR/Guidance-Element-Specification.rst b/docs/commons/fair/guidance-element-specification.rst similarity index 100% rename from docs/commons/FAIR/Guidance-Element-Specification.rst rename to docs/commons/fair/guidance-element-specification.rst diff --git a/docs/commons/FAIR/Shared-Tests.rst b/docs/commons/fair/shared-tests.rst similarity index 100% rename from docs/commons/FAIR/Shared-Tests.rst rename to docs/commons/fair/shared-tests.rst diff --git a/docs/commons/FAIR/Test-Algorithm-Registry.png b/docs/commons/fair/test-algorithm-registry.png similarity index 100% rename from docs/commons/FAIR/Test-Algorithm-Registry.png rename to docs/commons/fair/test-algorithm-registry.png diff --git a/docs/commons/skg/mappings/index.rst b/docs/commons/skg/mappings/index.rst index 7fe3ee2..1b71019 100644 --- a/docs/commons/skg/mappings/index.rst +++ b/docs/commons/skg/mappings/index.rst @@ -43,7 +43,6 @@ Below, we list SKG mappings defined for commonly used scholarly metadata sources :maxdepth: 1 :titlesonly: - DDI SKG-IF mapping - RO-Crate SKG-IF mapping - OpenAIRE Graph SKG-IF mapping - + DDI SKG-IF mapping + RO-Crate SKG-IF mapping + OpenAIRE Graph SKG-IF mapping diff --git a/docs/commons/skg/mappings/Mapping-SKGIF-DDI.rst b/docs/commons/skg/mappings/skg-if-ddi.rst similarity index 100% rename from docs/commons/skg/mappings/Mapping-SKGIF-DDI.rst rename to docs/commons/skg/mappings/skg-if-ddi.rst diff --git a/docs/commons/skg/mappings/Mapping-SKGIF-OpenAIRE.rst b/docs/commons/skg/mappings/skg-if-openaire.rst similarity index 100% rename from docs/commons/skg/mappings/Mapping-SKGIF-OpenAIRE.rst rename to docs/commons/skg/mappings/skg-if-openaire.rst diff --git a/docs/commons/skg/mappings/Mapping-SKGIF-RO-Crate.rst b/docs/commons/skg/mappings/skg-if-rocrate.rst similarity index 100% rename from docs/commons/skg/mappings/Mapping-SKGIF-RO-Crate.rst rename to docs/commons/skg/mappings/skg-if-rocrate.rst diff --git a/docs/index.rst b/docs/index.rst index cda6386..06fa33f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,9 +17,9 @@ The documentation is structured as follows: :caption: Architecture Introduction - DMP IF - SKG IF - FAIR IF + DMP IF + SKG IF + FAIR IF .. toctree:: @@ -30,16 +30,17 @@ The documentation is structured as follows: Governance DMP Commons SKG Commons - FAIR Commons + FAIR Commons .. toctree:: :maxdepth: 4 :caption: Tools - FAIR Tools - DMP Tools - SKG Tools + FAIR Tools + DMP Tools + SKG Tools + .. toctree:: :maxdepth: 4 diff --git a/docs/tools/FAIR.rst b/docs/tools/FAIR.rst deleted file mode 100644 index 92139cd..0000000 --- a/docs/tools/FAIR.rst +++ /dev/null @@ -1,18 +0,0 @@ -OSTrails FAIR Tools -==================== - - -The following resources in this section are part of the FAIR Tools component. - -.. toctree:: - :caption: Tools - :maxdepth: 1 - :titlesonly: - - FAIR Champion - FOOPS - FAIROS - FAIRsharing - FAIR Assessment Authoring Tool - FAIR Validator - diff --git a/docs/tools/FAIR_tools/fairassist-principles-navigation.png b/docs/tools/FAIR_tools/fairassist-principles-navigation.png deleted file mode 100644 index a1fea22..0000000 Binary files a/docs/tools/FAIR_tools/fairassist-principles-navigation.png and /dev/null differ diff --git a/docs/tools/FAIR_tools/fairassist-search-filter.png b/docs/tools/FAIR_tools/fairassist-search-filter.png deleted file mode 100644 index aece2dd..0000000 Binary files a/docs/tools/FAIR_tools/fairassist-search-filter.png and /dev/null differ diff --git a/docs/tools/DMP.rst b/docs/tools/dmp.rst similarity index 100% rename from docs/tools/DMP.rst rename to docs/tools/dmp.rst diff --git a/docs/tools/fair.rst b/docs/tools/fair.rst new file mode 100644 index 0000000..facb4a2 --- /dev/null +++ b/docs/tools/fair.rst @@ -0,0 +1,18 @@ +OSTrails FAIR Tools +==================== + + +The following resources in this section are part of the FAIR Tools component. + +.. toctree:: + :caption: Tools + :maxdepth: 1 + :titlesonly: + + FAIR Champion + FOOPS + FAIROS + FAIRsharing + FAIR Assessment Authoring Tool + FAIR Validator + diff --git a/docs/tools/FAIR_tools/FAIR-Assessment-Authoring-Tool.rst b/docs/tools/fair/fair-assessment-authoring-tool.rst similarity index 100% rename from docs/tools/FAIR_tools/FAIR-Assessment-Authoring-Tool.rst rename to docs/tools/fair/fair-assessment-authoring-tool.rst diff --git a/docs/tools/FAIR_tools/FAIR-Champion.rst b/docs/tools/fair/fair-champion.rst similarity index 100% rename from docs/tools/FAIR_tools/FAIR-Champion.rst rename to docs/tools/fair/fair-champion.rst diff --git a/docs/tools/FAIR_tools/FAIR-Validator.rst b/docs/tools/fair/fair-validator.rst similarity index 100% rename from docs/tools/FAIR_tools/FAIR-Validator.rst rename to docs/tools/fair/fair-validator.rst diff --git a/docs/tools/FAIR_tools/FAIROS.rst b/docs/tools/fair/fairos.rst similarity index 100% rename from docs/tools/FAIR_tools/FAIROS.rst rename to docs/tools/fair/fairos.rst diff --git a/docs/tools/FAIR_tools/FAIRsharing.rst b/docs/tools/fair/fairsharing.rst similarity index 100% rename from docs/tools/FAIR_tools/FAIRsharing.rst rename to docs/tools/fair/fairsharing.rst diff --git a/docs/tools/FAIR_tools/FOOPS.rst b/docs/tools/fair/foops.rst similarity index 100% rename from docs/tools/FAIR_tools/FOOPS.rst rename to docs/tools/fair/foops.rst diff --git a/docs/tools/SKG.rst b/docs/tools/skg.rst similarity index 77% rename from docs/tools/SKG.rst rename to docs/tools/skg.rst index 58b5acb..c5bbb0b 100644 --- a/docs/tools/SKG.rst +++ b/docs/tools/skg.rst @@ -10,6 +10,6 @@ The following resources in this section are part of the SKG Tools component. :maxdepth: 1 :titlesonly: - OpenAIRE Graph SKG-IF API - RO-HUB SKG-IF API - CESSDA SKG-IF API + OpenAIRE Graph SKG-IF API + RO-HUB SKG-IF API + CESSDA SKG-IF API diff --git a/docs/tools/SKG_tools/cessda.rst b/docs/tools/skg/cessda.rst similarity index 100% rename from docs/tools/SKG_tools/cessda.rst rename to docs/tools/skg/cessda.rst diff --git a/docs/tools/SKG_tools/SKG-OpenAIRE-Graph.png b/docs/tools/skg/openaire-graph.png similarity index 100% rename from docs/tools/SKG_tools/SKG-OpenAIRE-Graph.png rename to docs/tools/skg/openaire-graph.png diff --git a/docs/tools/SKG_tools/openaire.rst b/docs/tools/skg/openaire.rst similarity index 99% rename from docs/tools/SKG_tools/openaire.rst rename to docs/tools/skg/openaire.rst index 8de55ad..c2417a7 100644 --- a/docs/tools/SKG_tools/openaire.rst +++ b/docs/tools/skg/openaire.rst @@ -17,7 +17,7 @@ The OpenAIRE Graph employs a comprehensive data model that encapsulates a divers The graph not only represents these entities but also illustrates the relationships between them. This interconnectedness allows users to explore citations, collaborations, project affiliations, and software dependencies among a vast network of research products. -.. figure:: SKG-OpenAIRE-Graph.png +.. figure:: openaire-graph.png :alt: SKG OpenAIRE Graph :align: center diff --git a/docs/tools/SKG_tools/rohub.rst b/docs/tools/skg/rohub.rst similarity index 100% rename from docs/tools/SKG_tools/rohub.rst rename to docs/tools/skg/rohub.rst