[pull] master from go101:master

pages/apps-and-libs/golds.tmd

@@ -0,0 +1,151 @@
+######################### Golds
+
+**%% Golds %%** is an experimental Go local docs server,
+a Go docs generator, and a Go code reader.
+
+- Demo: __docs and source code of standard packages__
+  (generated with `GOEXPERIMENT=arenas golds -gen -nouses -only-list-exporteds -render-doclinks -theme=dark std`).
+- Code is __hosted on Github__. Any feedback, including PR and bug reports, are welcome.
+- Please follow __@zigo_101__ to get the latest news of **%% Golds %%**
+  (and all kinds of Go details/facts/tips/etc.).
+
+  //// __docs and ... `` https://docs.go101.org/index.html
+  //// __hosted on Github `` https://github.com/go101/golds
+  //// __@zigo_101 `` https://twitter.com/zigo_101
+
+#======================= Features and Limitations
+
+Please read __the project home page__ for details.
+
+  //// __the project home page `` https://github.com/go101/golds
+
+#======================= Installation
+
+Run `go install go101.org/golds@latest` to install Golds.
+If the tool program name `golds` conflicts with another tool with the same name you are using,
+you can run any of the following commands to install **%% Golds %%** as a program with a different name:
+
+- Go docs generator: run `go install go101.org/golds/godoge@latest`
+- Go code reader: run `go install go101.org/golds/gocore@latest`
+- Go local docs (mainly for legacy. `gold` was the old default program name of **%% Golds %%**):
+  run `go install go101.org/golds/gold@latest`  
+
+You may also clone this project firstly, then run the `go install` command
+in the respective program folders to install **%% Golds %%** as `golds`, `godoge`, or `gocore`.
+
+(NOTE: Go commands will install produced binaries into the Go binary installation path
+specified by the `GOBIN` environment variable, which defaults to the path of
+the `bin` subfolder under the first path specified in the `GOPATH` environment variable,
+which defaults to the path of the `go` subfolder under the path specified
+by the `HOME` environment variable.
+Please specify the Go binary installation path in the `PATH` environment variable
+to run **%% Golds %%** commands successfully.)
+
+#================================= Usages
+
+The main usage of **%% Golds %%** is to start a local docs server for a project,
+to either read package docs or study source code of the project. We can
+
+- run `golds .` to show docs of the package in the current directory
+  (and all its dependency packages).
+- run `golds ./...` to show docs of all the package under the current directory
+  (and all their dependency packages).
+- run `golds toolchain` (or `golds cmd`) to show docs of official toolchain packages.
+- run `golds std` to show docs of standard packages.
+  `std` can be mixed with any one of the above three arguments.
+- run `golds aPackage[/...][@aVersion]` to show docs of the specified packages
+  (and all their dependency packages).
+- run `golds foo.go bar.go baz.go` to show docs of the specified files
+  (and all their dependency packages).
+
+Each of the above commands will open a browser window automatically.
+We can use the `-s` or `-silent` options to turn off the behavior.
+
+The second usage of **%% Golds %%** is to generate static HTML doc pages for a project,
+with the `-gen` option:
+
+- `golds -gen -dir=generated -nouses .`
+- `golds -gen -dir=generated -nouses ./...`
+- `golds -gen -dir=generated -nouses std`
+
+The `-dir` option is optional and its default value is `.`(the working directory).
+The `-nouses` option used here is to generate docs with moderate sizes.
+
+The option `-source-code-reading` is used to control how to generate source code pages.
+Available values:
+
+- `plain`: generate simpler source code pages (no highlighting and no code navigations to reduce the total page size by 1/6 of the full docs size).
+- `highlight`: only highlight keywords and basic literals (no code navigations).
+- `rich`: rich code reading experience.
+- `external`: link to external code host websites (try its best, use `highlight` when failed).
+
+The option `-allow-network-connection` specifies whether or not network connections are allowed in determining external code host websites.
+
+Options to control generated docs sizes:
+
+- `-nouses`: don't generate identifier-uses pages (identifier-uses pages will occupy about 9/10 of the total page count and 2/3 of the full docs size).
+- `-source-code-reading=plain`
+- `-only-list-exporteds`: don't list unexported package-level code elements in package-details pages.
+- `-compact` is a shortcut of the combination of the above compact docs generation options.
+- Using `-source-code-reading=external` along with `-compact` will further reduce the generated docs size.
+
+The size of the docs generated by `golds -gen -compact ./...` is about 1/6 of `golds -gen ./...` and about 1/2 of `golds -gen -nouses ./...`. The size of the docs generated by `golds -gen -compact -source-code-reading=external ./...` is about 1/6 of `golds -gen -compact ./...`.
+
+The `-wdpkgs-listing` option is used to specify how to list the packages in the working directory. Available values include
+
+- `general` (the default, list them with others by alphabetical order)
+- `promoted` (list them before others)
+- `solo` (list them without others)
+
+The `-render-doclinks` option is used to control whether or not to render links in docs.
+
+The `-theme` option is used to control page styling
+ Supported values include `auto` (default), `light` and `dark`.
+ The `auto` value is equivalent to `light` plus custom styling set
+ in the `UserConfigDir/golds/custom.css` file (if it exists).
+
+The third usage of **%% Golds %%** is to serve files within a directory
+("Golds" also means Go local directory server).
+For example, we can run `golds -dir=.` (or simply `golds`) from the HTML docs generation directory to view the generated docs in browser. The `-s` and `-silent` options also work in this mode.
+
+The `golds` command recognizes the `GOOS` and `GOARCH` environment variables.
+
+#================================ FAQ
+
+#? What does **%% Golds %%** mean?
+
+"Golds" is an abbreviation of **Go** **l**ocal **d**ocs **s**erver.
+It also means **Go** **l**ocal **d**irectory **s**erver.
+
+#? Why **%% Golds %%**?
+
+{
+I didn't find a Go tool showing type implementation relations,
+so I decided to write one. During achieving this,
+I got many new ideas which form the tool to the final **%% Golds %%** design.
+
+I also have some different design opinions from the official `godoc` program developers,
+such as __the manner of listing factory functions__.
+
+  //// __the manner... `` https://github.com/golang/go/issues/28006
+
+Golds also tries to fix some shortcomings of `godoc` and `go doc`,
+such as __this``https://github.com/golang/go/issues/6600__,
+__this``https://github.com/golang/go/issues/40360__
+and __this``https://github.com/golang/go/issues/5860__.
+}
+
+#? Is **%% Golds %%** recommended to run locally?
+
+Yes. But if you do want to serve your package docs on Internet,
+it is best to serve the generated HTML static doc pages to lower the server cost.
+
+#? What are the requirements to run **%% Golds %%**?
+
+{
+If a Go project needs cgo, then a proper C/C++ compiler is needed.
+
+Some projects might need large memory capacity to analyze.
+For example, the recommended memory capacity to analyze the Kubernetes project is 8G+.
+However, 500M to 2G memory is okay for most Go projects.
+}