Make doc links in generated documentation relative (#300)

* updated doc links and made links relative in generated docs

README.md

@@ -19,7 +19,7 @@ lifecycle and interact with the core services and solutions in the platform.
 
 ## Documentation
 
-The `fsoc` [user documentation](https://developer.cisco.com/docs/fso/#!overview/overview) is published in Cisco's DevNet as part of the [platform documentation](https://developer.cisco.com/docs/fso/). 
+The `fsoc` [user documentation](https://developer.cisco.com/docs/cisco-observability-platform/#!overview/overview) is published in Cisco's DevNet as part of the [platform documentation](https://developer.cisco.com/docs/cisco-observability-platform/). 
 
 As `fsoc` is still evolving quickly, the DevNet documentation may sometimes not include information about the latest released version of `fsoc`. The `fsoc help` command is always the best way to get the correct help for the version of fsoc you have. Most commands provide sample command lines you can try.
 
@@ -123,7 +123,7 @@ fsoc login # test access
 
 NOTE: The login command will pop up a browser to perform the log in and then continue executing the command. Subsequent invocations of fsoc will use cached credentials. 
 
-Use the `fsoc help config set` command to see examples of the different authentication methods that `fsoc` supports in addition to OAuth (e.g., service principal, agent principal, local). You can find additional details in the `fsoc` [config page](https://developer.cisco.com/docs/fso/#!install-and-configure-fsoc/configure-access) in the platform docs.
+Use the `fsoc help config set` command to see examples of the different authentication methods that `fsoc` supports in addition to OAuth (e.g., service principal, agent principal, local). You can find additional details in the `fsoc` [config page](https://developer.cisco.com/docs/cisco-observability-platform/#!install-and-configure-fsoc/configure-access) in the platform docs.
 
 ## Assistance and Suggestions
 

cmd/gendocs/gendocs.go

@@ -23,6 +23,7 @@ import (
  "fmt"
  "os"
  "path/filepath"
+ "regexp"
  "strings"
 
  "github.com/apex/log"
@@ -36,6 +37,11 @@ import (
 
 const TOCFileName = "pages.json"
 
+const DocLinkUrl = "https://developer.cisco.com/docs/cisco-observability-platform"
+
+// DocLinkReplaceRegexp is a regular expression to match absolute links to the platform documentation, capturing the topic as $1
+var gblLinkReplaceRegexp = regexp.MustCompile(regexp.QuoteMeta(DocLinkUrl+`/#!`) + `(.*?)(\s|$|\.\s|\.$)`)
+
 // gendocsCmd represents the gendocs command
 var gendocsCmd = &cobra.Command{
  Use: "gendocs PATH",
@@ -54,6 +60,8 @@ The directory should either be empty or not exist.`,
 func NewSubCmd() *cobra.Command {
  gendocsCmd.Flags().
  Bool("h1", true, "adjust generated headings to start from h1 rather than h2")
+ gendocsCmd.Flags().
+ Bool("rel-links", true, "adjust generated platform doc links to become relative")
  return gendocsCmd
 }
 
@@ -108,17 +116,19 @@ func genDocs(cmd *cobra.Command, args []string) {
  log.Fatalf("Error generating fsoc docs table of contents: %v", err)
  }
 
- if cmd.Flag("h1").Changed {
- log.Infof("Editing headers in files\n")
+ flagH1, _ := cmd.Flags().GetBool("h1")
+ flagRelLinks, _ := cmd.Flags().GetBool("rel-links")
+ if flagH1 || flagRelLinks {
+ log.Infof("Processing files: h1=%v, rel-links=%v", flagH1, flagRelLinks)
 
  files := getListOfFiles(path)
- log.Infof("There are %d files to edit\n", len(files))
+ log.Infof("There are %d files to process", len(files))
 
  for i := 0; i < len(files); i++ {
  file := files[i]
- log.Infof("Starting to process file %s\n", file.Name())
+ log.Infof("Processing file %q", file.Name())
 
- err := processFile(file)
+ err := processFile(file, flagH1, flagRelLinks)
  if err != nil {
  log.Fatalf(err.Error())
  }
@@ -141,20 +151,12 @@ func genTableOfContents(cmd *cobra.Command, path string, fs *afero.Afero) error
  // generate TOC in memory
  toc := tocEntry{Items: []tocEntry{*genTOCNode(root)}}
 
- // display TOC if verbose
- if verbose, _ := root.Flags().GetBool("verbose"); verbose {
- if err := output.PrintJson(cmd, toc); err != nil {
- return fmt.Errorf("failed to marshal TOC to JSON: %v", err)
- }
- }
-
  // write TOC to file (rw permissions & umask)
  tocPath := filepath.Join(path, TOCFileName)
  tocFile, err := fs.OpenFile(tocPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0666)
  if err != nil {
  return fmt.Errorf("failed to open TOC file %v: %v", path, err)
  }
-
  if err = output.WriteJson(toc, tocFile); err != nil {
  return fmt.Errorf("failed to write TOC file %v: %v", path, err)
  }
@@ -197,12 +199,13 @@ func getListOfFiles(dir string) []*os.File {
  err := filepath.Walk(dir,
  func(path string, info os.FileInfo, err error) error {
  if err != nil {
+ log.Warnf("Error walking files at %q: %v", path, err)
  return err
  }
  file := getFileFromArgs(path)
  isFileMarkdown := strings.Contains(file.Name(), ".md")
  if isFileMarkdown {
- log.Infof("Adding %s to the list of files to edit\n", file.Name())
+ log.Infof("Adding %q to the list of files to process", file.Name())
  files = append(files, file)
  }
  return nil
@@ -213,7 +216,7 @@ func getListOfFiles(dir string) []*os.File {
  return files
 }
 
-func processFile(file *os.File) error {
+func processFile(file *os.File, modifyHeaderLevels bool, makeDocLinksRelative bool) error {
  fileScanner := bufio.NewScanner(file)
  fileScanner.Split(bufio.ScanLines)
  var fileLines []string
@@ -223,16 +226,34 @@ func processFile(file *os.File) error {
  }
  for i := 0; i < len(fileLines); i++ {
  line := fileLines[i]
- if len(line) > 2 {
- if line[0:2] == "##" {
- fileLines[i] = line[1:]
+ if modifyHeaderLevels {
+ if len(line) > 2 {
+ if line[0:2] == "##" {
+ fileLines[i] = line[1:]
+ }
+ }
+
+ // the following two changes are not header level changes but related to meeting the same doc requirements
+ if fileLines[i] == "## SEE ALSO" {
+ fileLines[i] = "## See Also"
+ }
+ if fileLines[i] == "## Options inherited from parent commands" {
+ fileLines[i] = "## Options Inherited From Parent Commands"
  }
  }
- if fileLines[i] == "## SEE ALSO" {
- fileLines[i] = "## See Also"
- }
- if fileLines[i] == "## Options inherited from parent commands" {
- fileLines[i] = "## Options Inherited From Parent Commands"
+ if makeDocLinksRelative {
+ oldLine := fileLines[i]
+
+ // replace topic links, changing from an absolute URL to a markdown doc root-relative link
+ fileLines[i] = gblLinkReplaceRegexp.ReplaceAllString(fileLines[i], `[$1](/#!$1)$2`)
+
+ // replace any remaining absolute links
+ fileLines[i] = strings.ReplaceAll(fileLines[i], DocLinkUrl, "[platform documentation](./)")
+
+ // log change
+ if fileLines[i] != oldLine {
+ log.Infof("Changed link %d: %q -> %q", i, oldLine, fileLines[i])
+ }
  }
  }
 

cmd/knowledge/knowledge.go

@@ -39,7 +39,7 @@ func NewSubCmd() *cobra.Command {
  Long: `
 Perform Knowledge Store operations. "ks" is a convenient alias to the "knowledge" command.
 
-See https://developer.cisco.com/docs/fso/#!knowledge-store-introduction/introduction for more information on the Knowledge Store.
+See https://developer.cisco.com/docs/cisco-observability-platform/#!knowledge-store-introduction for more information on the Knowledge Store.
 
 All operations require the type to be specified as a fully-qualified type name (FQTN). FQTN follows the format solutionName:typeName (e.g., extensibility:solution).
 

cmd/root.go

@@ -57,7 +57,7 @@ var rootCmd = &cobra.Command{
  Use: "fsoc GROUP [COMMAND] [FLAGS...] [ARGUMENTS...]",
  Short: "fsoc - Cisco Observability Platform Control Tool",
  Long: `fsoc is an open source utility that serves as a command line interface to the Cisco Observability
-Platform (https://developer.cisco.com/docs/fso/). 
+Platform (https://developer.cisco.com/docs/cisco-observability-platform). 
 
 fsoc provides a set of commands to interact with the platform. It allows developers to interact in a uniform way
 with the platform's different environments (development, test, production) and conveniently switch between them.
@@ -74,7 +74,7 @@ fsoc logs its execution details into a log file. By default, fsoc shows only war
 the output. You can use the --verbose flag to show all log messages and/or the --log flag to set a desired location
 for saving the log file.
 
-Detailed user docs for fsoc are available at https://developer.cisco.com/docs/fso/#!overview/overview.
+Detailed user docs for fsoc are available at https://developer.cisco.com/docs/cisco-observability-platform/#!overview.
 For source code and build instructions, see also https://github.com/cisco-open/fsoc.
 
 NOTE: fsoc is in alpha; breaking changes may occur.`,

cmd/solution/push.go

@@ -29,7 +29,7 @@ Important details on solution tags:
 (1) A tag must be associated with the solution being uploaded. All subsequent solution upload requests should use this same tag
 (2) Use caution when supplying the tag value to the solution to upload as typos can result in misleading validation results
 (3) 'stable' is a reserved tag value keyword for production-ready versions and hence should be used appropriately
-(4) For more info on tags, please visit: https://developer.cisco.com/docs/fso/#!tag-a-solution
+(4) For more info on tags, please visit: https://developer.cisco.com/docs/cisco-observability-platform/#!tag-a-solution
 `,
  Example: `
  fsoc solution push --tag=stable

cmd/solution/solution.go

@@ -29,7 +29,7 @@ var solutionCmd = &cobra.Command{
  Short: "Perform solution operations",
  Long: `Perform solution lifecycle and control operations.
 
-For more information on platform solutions, see https://developer.cisco.com/docs/fso/#!create-a-solution-introduction`,
+For more information on platform solutions, see https://developer.cisco.com/docs/cisco-observability-platform/#!create-a-solution-introduction`,
  Example: ` fsoc solution list`,
  TraverseChildren: true,
 }

cmd/uql/uql.go

@@ -49,7 +49,7 @@ var uqlCmd = &cobra.Command{
  Short: "Perform UQL query",
  Long: `Perform a Unified Query Language query of MELT data for a tenant. 
 
-See https://developer.cisco.com/docs/fso/#!data-query-using-unified-query-language
+See https://developer.cisco.com/docs/cisco-observability-platform/#!data-query-using-unified-query-language
 for more information on the unified query language for the Cisco Observability Platform.
 
 Parsed response data are displayed in a table by default.