More doc updates

README.md

@@ -124,7 +124,7 @@ There's much more cusomization possible with `clowder`. For some more complex ex
 
 [Forks clowder.yml](docs/clowder-yml-forks.md)
 
-[clowder.yml Syntax](docs/clowder-yml-syntax.md)
+[clowder.yml Syntax Reference](docs/clowder-yml-syntax-reference.md)
 
 ## Basic Usage
 

docs/clowder-yml-syntax.md → docs/clowder-yml-syntax-reference.md

@@ -1,4 +1,4 @@
-# `clowder.yml` Syntax
+# `clowder.yml` Syntax Reference
 
 - [name](#name) **Required**
 - [defaults](#defaults) **Required**
@@ -29,6 +29,9 @@
 - [projects.fork.name](#projectsforkname)
 - [projects.fork.source](#projectsforksource)
 - [projects.fork.remote](#projectsforkremote)
+- [projects.fork.branch](#projectsforkbranch)
+- [projects.fork.tag](#projectsforktag)
+- [projects.fork.commit](#projectsforkcommit)
 - [projects.git.lfs](#projectsgitlfs)
 - [projects.git.recursive](#projectsgitrecursive)
 - [projects.git.depth](#projectsgitdepth)
@@ -82,7 +85,7 @@ The default depth git will clone repositories. Must be a positive integer. If se
 
 ### `defaults.git.config`
 
-A map of git config values to install in projects. During an initial clone, they will be installed at the end. Later invocations of `clowder herd` will install the config values before running other commands. This can be overridden by setting [projects.git.config](#projectsgitconfig). Git config values from defaults will be combined with those in [projects.git.confg](#projects.git.config). If the same keys are present, the project value will take priority. To prevent a default git config value from being inherited by a project, it must be set to `null` in [projects.git.config](#projectsgitconfig).
+A map of git config values to install in projects. During an initial clone, they will be installed at the end. Later invocations of `clowder herd` will install the config values before running other commands. This can be overridden by setting [projects.git.config](#projectsgitconfig). Git config values from defaults will be combined with those in [projects.git.confg](#projectsgitconfig). If the same keys are present, the project value will take priority. To prevent a default git config value from being inherited by a project, it must be set to `null` in [projects.git.config](#projectsgitconfig).
 
 ### `sources`
 
@@ -152,6 +155,18 @@ Name from [sources.name](#sourcesname) to use for forming git clone url. See als
 
 Git remote name. See also [defaults.remote](#defaultsremote).
 
+### `projects.fork.branch`
+
+Name of the Git branch to track for this project fork. Only one of `branch`, `tag`, or `commit` can be present. If not supplied and `tag` or `commit` are not specified in [projects.fork](#projectsfork) or [defaults](#defaults), the default branch `master` is used.
+
+### `projects.fork.tag`
+
+Name of the Git tag to track for this project fork. Only one of `tag`, `tag`, or `commit` can be present. If not supplied and `branch` or `commit` are not specified in [projects.fork](#projectsfork) or [defaults](#defaults), the default branch `master` is used.
+
+### `projects.fork.commit`
+
+A git commit SHA-1 to track for this project fork. Must be full 40 character SHA-1. Only one of `commit`, `tag`, or `commit` can be present. If not supplied and `branch` and `tag` are not specified in [projects.fork](#projectsfork) or [defaults](#defaults), the default branch `master` is used.
+
 ### `projects.git.lfs`
 
 Setting this value to `true` will cause clowder to install git lfs hooks and pull lfs files when `clowder herd` is run. See also [defaults.git.lfs](#defaultsgitlfs)
@@ -166,4 +181,4 @@ The default depth git will clone repositories. Must be a positive integer. If se
 
 ### `projects.git.config`
 
-A map of git config values to install in the project. During an initial clone, they will be installed at the end. Later invocations of `clowder herd` will install the config values before running other commands. Git config values from [defaults.git.confg](#defaults.git.config) will be combined with those in the project. If the same keys are present, the project value will take priority. To prevent a value from [defaults.git.config](#defaultsgitconfig) from being inherited by the project, it must be set to `null`. See also [defaults.git.config](#defaultsgitconfig)
+A map of git config values to install in the project. During an initial clone, they will be installed at the end. Later invocations of `clowder herd` will install the config values before running other commands. Git config values from [defaults.git.confg](#defaultsgitconfig) will be combined with those in the project. If the same keys are present, the project value will take priority. To prevent a value from [defaults.git.config](#defaultsgitconfig) from being inherited by the project, it must be set to `null`. See also [defaults.git.config](#defaultsgitconfig)

docs/conf.py

@@ -16,13 +16,53 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
-import os
 import sys
-CLOWDER_DIR = os.path.join('..', 'clowder')
-sys.path.insert(0, os.path.abspath(CLOWDER_DIR))
+from pathlib import Path
+
+CLOWDER_DIR = str(Path('../clowder').resolve())
+sys.path.insert(0, CLOWDER_DIR)
 
 import clowder
 
+# -- Fix header links in markdown files -----------------------------------
+
+clowder_yaml_syntax_reference_file = Path('clowder-yml-syntax-reference.md').resolve()
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_file.read_text()
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultsprotocol", "#defaults-protocol")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultssource", "#defaults-source")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultsremote", "#defaults-remote")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultsbranch", "#defaults-branch")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultstag", "#defaults-tag")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultscommit", "#defaults-commit")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultsgitlfs", "#defaults-git-lfs")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultsgitrecursive", "#defaults-git-recursive")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultsgitdepth", "#defaults-git-depth")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#defaultsgitconfig", "#defaults-git-config")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#sourcesname", "#sources-name")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#sourcesurl", "#sources-url")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#sourcesprotocol", "#sources-protocol")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsname", "#projects-name")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectssource", "#projects-source")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsbranch", "#projects-branch")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectstag", "#projects-tag")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectscommit", "#projects-commit")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectspath", "#projects-path")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsremote", "#projects-remote")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsgroups", "#projects-groups")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsforkname", "#projects-fork-name")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsforksource", "#projects-fork-source")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsforkremote", "#projects-fork-remote")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsforkbranch", "#projects-fork-branch")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsforktag", "#projects-fork-tag")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsforkcommit", "#projects-fork-commit")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsgitlfs", "#projects-git-lfs")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsgitrecursive", "#projects-git-recursive")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsgitdepth", "#projects-git-depth")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsgitconfig", "#projects-git-config")
+clowder_yaml_syntax_reference_contents = clowder_yaml_syntax_reference_contents.replace("#projectsfork", "#projects-fork")
+with clowder_yaml_syntax_reference_file.open("w", encoding="utf-8") as f:
+    f.write(clowder_yaml_syntax_reference_contents)
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

docs/general_documentation.rst

@@ -6,7 +6,7 @@ General Documentation
    :maxdepth: 2
 
    Command Reference <commands>
-   clowder.yml Syntax <clowder-yml-syntax>
+   clowder.yml Syntax Reference <clowder-yml-syntax-reference>
    The clowder repo <clowder-repo>
    Forks <forks>
    Examples <examples>

src/requirements.txt

@@ -12,6 +12,7 @@ remarshal
 sphinx
 sphinx-autobuild
 sphinx-rtd-theme
+# sphinx_rtd_theme
 termcolor
 tqdm
 twine