Write documentation with go code in a declarative way to create beautiful documentation
Why use docgo
+
+
The developer community often use markdown or in Python world use Sphinx and reStructuredText to create tech documentations, We think they are nice, But because of these reasons we created this package for the Go community:
+
+
+- Work together with snippetgo to use real executable code as example code blocks in documentation, So that it won't be invalid or obsolete after code change, Since Go compiler will pick out the errors and you will have to fix the examples to make compiler happy, and the documentation is automatically updated.
+- Write documentation in Go code not only you can still write markdown, But also you can access the flexibility of a programming language, to use components, and reuse parts that are duplicated.
+- Documents exists inside go code, means it can be distributed as go packages, so it wont' be restricted with directory layout.
+- Make developer focus on writing documentation, instead of worrying about document styles, the default document styles is following the Swift DocC with minor changes. So we think it is good enough for most projects
+
+
+
Getting Started
+
+
The following code is used to build this doc
+Hello World
+
+
+
+package docs
+
+import (
+ . "github.com/theplant/docgo"
+ ch "github.com/theplant/docgo/codehighlight"
+ . "github.com/theplant/htmlgo"
+)
+
+var HelloWorld = Doc(
+ Markdown(`
+## Overview
+
+Write some beautiful docs
+`),
+ Tip("This is quite important to learn"),
+
+ H2("A new section"),
+ P(Text("Doc of that section")),
+ ch.Code("var Hello = 123").Language("go"),
+).
+ Title("Hello World").
+ AbstractText(
+ "Hello world doc to describe how easy it is to create a doc",
+ )
+
+
+
+
Use the following code to boot up your doc app, Suppose you have already created a Home Doc in docs package.
+
+
+func main() {
+ port := os.Getenv("PORT")
+ if len(port) == 0 {
+ port = "8800"
+ }
+ fmt.Println("Starting docs at :" + port)
+ http.Handle("/", docgo.New().
+ Assets("/assets/", docs.Assets).
+ Home(docs.Home).
+ Build(),
+ )
+ err := http.ListenAndServe(":"+port, nil)
+ if err != nil {
+ panic(err)
+ }
+}
+
+
+
+
Children Docs
+
+
Use ChildrenTable(...) to put other docs into current doc page children, The doc url will reflect the hierarchy, children docs url will contain parent doc slug
+
+
+var HelloWorldWithChildren = Doc(
+ Markdown(`
+## Overview
+
+Write some beautiful docs
+`),
+).Title("Hello World with children").
+ AbstractText("Hello world with children is to describe how to add children docs").
+ Tables(
+ ChildrenTable(
+ ContentGroup(
+ HowToSayHello,
+ HowToGoodBye,
+ ).Title("Essentials"),
+ ),
+ )
+
+var HowToSayHello = Doc(Markdown(`
+## Say Hello
+
+Hi, There
+
+~~~go
+var Hello = true
+~~~
+
+`)).Title("How to say hello")
+
+var HowToGoodBye = Doc(Markdown(`
+## Say Good Bye
+
+Bye, There
+
+`)).Title("How to say good bye")
+
+
+Check out this link to see how it works
+
Hello World with children
+