OpenPathY: A YAML-sourced schema for modeling, validating, and documenting filesystem/codebase paths

README.adoc

Imagine a schema for defining expected directory/file structures for your applications.

Define it all in YAML, then use a proper library to:

• validate an existing path structure against your schema

• generate model folder/file trees in arbitrary or logical order

• document your expected path structure based on properties of each dir/file key

Take a look at the following example schema.

data-model.yml

root/:
  _meta: # properties of this directory
    summ: Root directory for the project.
    desc: |
      This is the root directory for the project. It contains the configuration
      files and directories for the project.
  # after _meta, the rest of the keys are the names of files and directories
  src/:
    _meta:
      summ: Source code directory.
      reqd: true # path is required
      desc: |
        This directory contains the source code for the project. It may contain
        subdirectories for different parts of the project.
      alts: # alternative paths that could go here
        $ref: '#/root/src/lib' # in other words, the content at the indicated path could be slotted in here, recursively, su just lib/ instead of src/lib/
    lib/:
      _meta:
        summ: Application library files.
  _docs/:
    _meta:
      summ: Documentation directory.
      reqd: true
      desc: |
        This directory contains the documentation for the project.
    content/:
      topics/:
        <topic>.adoc:
          regx: /[a-z][a-z-_]+\.adoc/
          desc: As many AsciiDoc files as needed.
      common/:
        snippets/:
          _meta:
            summ: Code samples and other literals.
        partials/:
          _meta:
            summ: Collection of reusable content.
          <partial>.adoc:
            regx: /[a-z][a-z-_]+\.adoc/
          index.adoc:
           desc: AsciiDOc index file.
    data/:
      manifest.yml:
        type: config
        with: yaml
        summ: Documentation portals manifest.
  Gemfile:
    reqd: true
    type: config
    with: ruby
    summ: Ruby gem dependency listings.
    desc: |
      This file lists the Ruby gems required for the project.
      Sometimes it also lists specified versions of the gems.
  Gemfile.lock:
    reqd: true
    type: config
    with: ruby
    summ: Fixed Ruby dependency versions.
  .gitignore:
    type: config
    with: git
    summ: Files and directories _not to track_ in Git.
  .git/:
    _meta:
      view: hidden
      summ: Git repository and local Git metadata.
  

sample-pathtree-arbitrary.txt

root/
├── src/
│   └── lib/
├── _docs/
│   ├── content/
│   │   ├── topics/
│   │   ├── common/
│   │   │   ├── snippets/
│   │   │   └── partials/
│   │   │       └── <partal>.adoc
│   │   └── index.adoc
│   └── data/
│       └── manifest.yml
├── Gemfile
├── Gemfile.lock
├── .gitignore
└── .git/

sample-pathtree-logical.txt

root/
├── _docs/
│   ├── content/
│   │   ├── common/
│   │   │   ├── partials/
│   │   │   │   └── <partal>.adoc
│   │   │   └── snippets/
│   │   ├── topics/
│   │   │   └── <topic>.adpc
│   │   └── index.adoc
│   └── data/
│       └── manifest.yml
├── src/
│   └── lib/
├── .git/
├── Gemfile
├── Gemfile.lock
└── .gitignore

sample-pathtree-schema-docs.adoc

Here is sample auto-generated documentation of the path schema.

src/

Source code directory. (required)

This directory contains the source code for the project. It may contain subdirectories for different parts of the project.

Optionally substitute src/lib/ path here.

lib/

Application library files.

_docs/

Documentation directory. (required)

This directory contains the documentation for the project.

content/

Topics and common content for documentation.

topics/

Specific topics related to the project.

common/

Shared resources and content for multiple topics.

snippets/ Code samples and other literals.

partials/ Collection of reusable content.

index.adoc

AsciiDOc index file.

data/

Stores manifest and other data files for documentation portals.

manifest.yml

Documentation portals manifest.

Gemfile

Ruby gem dependency listings. (required)

This file lists the Ruby gems required for the project. Sometimes it also lists specified versions of the gems.

Gemfile.lock

Fixed Ruby dependency versions. (required)

.gitignore

Files and directories not to track in Git.

simple-pathy-schema.yml

root/:
  lib/:
  _docs/:
    content/:
      topics/:
        <topic>.adoc:
      common/:
        snippets/:
        partials/:
          <partial>.adoc:
        index.adoc:
    data/:
      manifest.yml:
  .gitignore:
  .git/:
  Gemfile:
  Gemfile.lock: