Generate docs for the CLI #40
Conversation
This POC provides a new command (`usage`) that is hidden from users, but would allow us to CD docs as part of our workflow.
Codecov Report
@@ Coverage Diff @@
## master #40 +/- ##
==========================================
- Coverage 39.39% 39.17% -0.22%
==========================================
Files 12 13 +1
Lines 853 878 +25
==========================================
+ Hits 336 344 +8
- Misses 493 510 +17
Partials 24 24
Continue to review full report at Codecov.
|
|
Pending review, this has been deployed here: |
cmd/usage.go
Outdated
| return true | ||
| } | ||
|
|
||
| func usage(cmd *cobra.Command, args []string) error { |
There was a problem hiding this comment.
I’d rather we did the call to Pandoc from outside go. I’d like to generate the .md content from go, and the exit.
Then in config.yml call out to pandoc to generate HTML.
.circleci/deploy-gh-pages.sh
Outdated
|
|
||
| # move index and update links | ||
| mv circleci.html index.html | ||
| sed -i -- 's#<a href="circleci.html">#<a href="index.html">#g' *.html |
There was a problem hiding this comment.
Can you do this moving and replacement from somewhere else, so that you his script is just concerned with pushing to gh-pages.
Having these two lines in the middle of this script is surprising to the reader.
cmd/root.go
Outdated
| @@ -13,6 +13,8 @@ import ( | |||
|
|
|||
| var defaultEndpoint = "https://circleci.com/graphql-unstable" | |||
|
|
|||
| var rootCmd *cobra.Command | |||
There was a problem hiding this comment.
Why did you make a global here?
We now generate the markdown comment from `usage` command, and call pandoc from a script to handle generating HTML.
|
The changes to I will have to check which version of |
|
After further review, it looks like the change to Which seems to have been released about 10 days ago: |
|
|
||
| # pandoc markdown to html into out dir | ||
| for f in docs/*.md; do | ||
| pandoc "$f" -s -o "out/$(basename ${f%.md}.html)"; |
There was a problem hiding this comment.
This bit of magic was in their FAQ 🙌
https://pandoc.org/faqs.html#how-can-i-convert-a-whole-directory-of-files-from-markdown-to-rtf
You can see a preview here:
https://852-137903064-gh.circle-artifacts.com/0/docs/circleci.html
Which was generated by this build:
https://circleci.com/gh/CircleCI-Public/circleci-cli/852#artifacts/containers/0