docs: reorg references into relevant sections; add #hof & @attrs page

hofstadter-io · May 19, 2024 · 5359081 · 5359081
1 parent 42d4ac0
commit 5359081
Show file tree

Hide file tree

Showing 45 changed files with 191 additions and 599 deletions.
diff --git a/docs/code/hof-schemas/hof.cue b/docs/code/hof-schemas/hof.cue
@@ -15,7 +15,6 @@ Hof: {
 
 		// hof/datamodel
 		datamodel?: {
-
 			// define the root of a datamodel
 			root: bool | *false
 
@@ -37,33 +36,24 @@ Hof: {
 
 		// hof/gen
 		gen?: {
+			// define the root of a generator
 			root: bool | *false
 
 			// name of the generator
 			name: string | *""
-
-			// TODO, do we need this? aren't we...
-			// determining based on the existence of Create: {}
-			creator: bool | *false
 		}
 
 		// hof/flow, used for both flows & tasks
 		flow?: {
+			// define the root of a workflow
 			root: bool | *false
 
 			// name of the flow or task
 			name: string | *""
 
 			// if op is empty, it is a flow value
 			// if op is not empty, it is a task value
-			// TODO, maybe we make this "flow" for flows?
-			op: string | *"flow"
-		}
-
-		chat?: {
-			root:  bool | *false
-			name:  string | *""
-			extra: string | *""
+			op: string | *""
 		}
 	}
 }
@@ -82,4 +72,4 @@ Metadata: {
 }
 
 // depreciated
-DHof: Hof
+DHof: Hof
diff --git a/docs/content/code-generation/adhoc/_index.md b/docs/content/code-generation/adhoc/_index.md
@@ -1,6 +1,7 @@
 ---
 Title: Ad-hoc Code Gen
 
+draft: true
 weight: 59
 ---
 

diff --git a/docs/content/code-generation/formatting/_index.md b/docs/content/code-generation/formatting/_index.md
@@ -26,6 +26,27 @@ see the [custom formatters](/code-generation/formatting/custom-formatters/) sect
 hof fmt
 ```
 
+{{<lead>}}
+`hof/fmt` is a command which will
+format any and all languages.
+You can create your own formatters as well.
+{{</lead>}}
+
+
+`hof` needs a code formatter for the languages it generates.
+It runs the pre-output through before applying diff and merging
+with any custom code you added to output files.
+This is simplifies the job of template authors,
+but is also required to avoid unnecessary merge conflicts.
+
+You will need Docker available to use this feature.
+Hof will pull and run containers in the background.
+You can disable this by setting an environment variable.
+
+> `HOF_FMT_DISABLED=1`
+
+
+{{<codePane file="code/cmd-help/fmt" title="$ hof help fmt" lang="text">}}
 
 ## Supported Languages
 

diff --git a/...ntent/reference/hof-datamodel/commands.md → docs/content/data-modeling/commands.md b/...ntent/reference/hof-datamodel/commands.md → docs/content/data-modeling/commands.md
diff --git a/...ent/reference/hof-datamodel/complexity.md → docs/content/data-modeling/complexity.md b/...ent/reference/hof-datamodel/complexity.md → docs/content/data-modeling/complexity.md
diff --git a/...nt/reference/hof-datamodel/composition.md → docs/content/data-modeling/composition.md b/...nt/reference/hof-datamodel/composition.md → docs/content/data-modeling/composition.md
diff --git a/...tent/reference/hof-datamodel/databases.md → docs/content/data-modeling/databases.md b/...tent/reference/hof-datamodel/databases.md → docs/content/data-modeling/databases.md
diff --git a/...tent/reference/hof-datamodel/extending.md → docs/content/data-modeling/extending.md b/...tent/reference/hof-datamodel/extending.md → docs/content/data-modeling/extending.md
diff --git a/...ent/reference/hof-datamodel/generators.md → docs/content/data-modeling/generators.md b/...ent/reference/hof-datamodel/generators.md → docs/content/data-modeling/generators.md
diff --git a/...tent/reference/hof-datamodel/languages.md → docs/content/data-modeling/languages.md b/...tent/reference/hof-datamodel/languages.md → docs/content/data-modeling/languages.md
diff --git a/...ce/hof-datamodel/migrations-and-lenses.md → ...nt/data-modeling/migrations-and-lenses.md b/...ce/hof-datamodel/migrations-and-lenses.md → ...nt/data-modeling/migrations-and-lenses.md
diff --git a/...ontent/reference/hof-datamodel/schemas.md → docs/content/data-modeling/schemas.md b/...ontent/reference/hof-datamodel/schemas.md → docs/content/data-modeling/schemas.md
diff --git a/...ce/hof-datamodel/snapshots-and-history.md → ...nt/data-modeling/snapshots-and-history.md b/...ce/hof-datamodel/snapshots-and-history.md → ...nt/data-modeling/snapshots-and-history.md
diff --git a/...ntent/reference/hof-datamodel/with_cue.md → docs/content/data-modeling/with_cue.md b/...ntent/reference/hof-datamodel/with_cue.md → docs/content/data-modeling/with_cue.md
diff --git a/docs/content/reference/command-help.md → docs/content/getting-started/command-help.md b/docs/content/reference/command-help.md → docs/content/getting-started/command-help.md
diff --git a/docs/content/reference/concepts.md → docs/content/getting-started/concepts.md b/docs/content/reference/concepts.md → docs/content/getting-started/concepts.md
@@ -3,6 +3,7 @@ title: "Concepts"
 description: "Overview of the main concepts in Hofstadter around code generation, source-of-truth, reusability."
 brief: "in Hofstadter, a quick overview"
 
+draft: true
 weight: 90
 ---
 

diff --git a/docs/content/getting-started/cue.md b/docs/content/getting-started/cue.md
@@ -47,3 +47,44 @@ To further your CUE knowledge, be sure to check out these resources:
 
 - [CUE documentation](https://cuelang.org) (from the CUE Team)
 - [Cuetorials](https://cuetorials.com) (by Hofstadter)
+
+
+### Hof & CUE Modules
+
+__hof__ has a preview version for __CUE modules__.
+Hof & CUE's modules serve the same purpose as other languages,
+allowing to to version, share, and reuse code.
+CUE's module system is still largely experimental.
+We will eventually migrate over once sufficient features
+are in place, at which point we will provide automation to update.
+
+Most of hof's features can be used from the module system.
+"`hof mod`" is the subcommand for working with modules and dependencies.
+The implementation is based on Go modules.
+
+The name of a module should be the same the git repository.
+`hof` talks directly to git repositories and many of
+`hof`'s commands will accept modules as an input argument too.
+There is also support for OCI based repositories.
+
+##### [To learn more, see the modules section](/modules/).
+
+<br>
+
+{{<codeInner>}}
+# create a new module
+hof mod init github.com/hofstadter-io/example
+
+# add a dependency
+hof mod get github.com/hofstadter-io/[email protected]
+  or
+hof mod get github.com/hofstadter-io/hof@latest
+
+# tidy dependencies
+hof mod tidy
+
+# fetch dependencies
+hof mod link
+  or
+hof mod vendor
+{{</codeInner>}}
diff --git a/docs/content/getting-started/hof-attributes.md b/docs/content/getting-started/hof-attributes.md
@@ -0,0 +1,16 @@
+---
+title: "#hof & @attributes"
+
+weight: 70
+---
+
+{{<lead>}}
+Hof denotes major features with a `#hof` definition
+and has several attributes you can use as shorthand.
+{{</lead>}}
+
+- @gen
+- @flow
+- @datamodel
+
+{{< codePane title="hof/schema.Hof" file="code/hof-schemas/hof.html" >}}
diff --git a/docs/content/getting-started/modules.md b/docs/content/getting-started/modules.md
diff --git a/docs/content/reference/_index.md b/docs/content/reference/_index.md