From 2945bc5968e2b9104155fd49fa77b65865233098 Mon Sep 17 00:00:00 2001 From: Yaroslav Halchenko Date: Fri, 18 Apr 2025 09:21:06 -0400 Subject: [PATCH] [ENH] Formalize presence of optional docs/ folder Inspired by the success of the https://github.com/bids-standard/bids-specification/pull/1962 adding formalization of `logs/` folder, and triggered by the use-case in DANDI https://github.com/dandi/dandi-docs/pull/200 seeking to add more elaborate descriptions to the README (or more specifically README.md), I would like to propose adding any extra documentation and associated artwork (images, videos, etc) under `docs/` folder. I do not think it is worth breaking down more (as videos/) etc, since it could confuse with data types (videos of behavior or alike). Not sure if we would want to formalize inner structure anyhow. We could potentially recommend using `docs/images/` subfolder for images. Then README.md on top level could potentially use those images via references to `docs/` paths. --- src/common-principles.md | 1 + src/schema/rules/directories.yaml | 4 ++++ src/schema/rules/files/common/core.yaml | 3 +++ 3 files changed, 8 insertions(+) diff --git a/src/common-principles.md b/src/common-principles.md index 269a27365b..2f5215c0f5 100644 --- a/src/common-principles.md +++ b/src/common-principles.md @@ -392,6 +392,7 @@ Derivatives can be stored/distributed in two ways: that were used to generate the derivatives. Likewise, any code used to generate the derivatives from the source data MAY be included in the `code/` subdirectory. + Extra documentation (and relevant images) MAY be included in the `docs/` subdirectory. Logs from running the code or other commands MAY be stored under `logs/` subdirectory. Example of a derivative dataset including the raw dataset as source: diff --git a/src/schema/rules/directories.yaml b/src/schema/rules/directories.yaml index 5f2fc7d129..3bfea7c26e 100644 --- a/src/schema/rules/directories.yaml +++ b/src/schema/rules/directories.yaml @@ -34,6 +34,10 @@ raw: name: derivatives level: optional opaque: true + docs: + name: docs + level: optional + opaque: true logs: name: logs level: optional diff --git a/src/schema/rules/files/common/core.yaml b/src/schema/rules/files/common/core.yaml index fa28b76904..fe8535d0ce 100644 --- a/src/schema/rules/files/common/core.yaml +++ b/src/schema/rules/files/common/core.yaml @@ -36,6 +36,9 @@ code: derivatives: level: optional path: derivatives +docs: + level: optional + path: docs logs: level: optional path: logs