github.com/apptainer/singularity@v3.1.1+incompatible/cmd/docs/docs.go (about)

     1  // Copyright (c) 2019, Sylabs Inc. All rights reserved.
     2  // This software is licensed under a 3-clause BSD license. Please consult the
     3  // LICENSE.md file distributed with the sources of this project regarding your
     4  // rights to use or distribute this software.
     5  
     6  package main
     7  
     8  import (
     9  	"fmt"
    10  	"github.com/spf13/cobra"
    11  	"github.com/spf13/cobra/doc"
    12  	"github.com/sylabs/singularity/cmd/internal/cli"
    13  	"github.com/sylabs/singularity/internal/pkg/sylog"
    14  	"golang.org/x/sys/unix"
    15  )
    16  
    17  func assertAccess(dir string) {
    18  	if err := unix.Access(dir, unix.W_OK); err != nil {
    19  		sylog.Fatalf("Given directory does not exist or is not writable by calling user.")
    20  	}
    21  }
    22  
    23  func markdownDocs(outDir string) {
    24  	assertAccess(outDir)
    25  	sylog.Infof("Creating Singularity markdown docs at %s\n", outDir)
    26  	if err := doc.GenMarkdownTree(cli.SingularityCmd, outDir); err != nil {
    27  		sylog.Fatalf("Failed to create markdown docs for singularity\n")
    28  	}
    29  }
    30  
    31  func manDocs(outDir string) {
    32  	assertAccess(outDir)
    33  	sylog.Infof("Creating Singularity man pages at %s\n", outDir)
    34  	header := &doc.GenManHeader{
    35  		Title:   "singularity",
    36  		Section: "1",
    37  	}
    38  
    39  	// works recursively on all sub-commands (thanks bauerm97)
    40  	if err := doc.GenManTree(cli.SingularityCmd, header, outDir); err != nil {
    41  		sylog.Fatalf("Failed to create man pages for singularity\n")
    42  	}
    43  }
    44  
    45  func rstDocs(outDir string) {
    46  	assertAccess(outDir)
    47  	sylog.Infof("Creating Singularity RST docs at %s\n", outDir)
    48  	if err := doc.GenReSTTreeCustom(cli.SingularityCmd, outDir, func(a string) string {
    49  		return ""
    50  	}, func(name, ref string) string {
    51  		return fmt.Sprintf(":ref:`%s <%s>`", name, ref)
    52  	}); err != nil {
    53  		sylog.Fatalf("Failed to create RST docs for singularity\n")
    54  	}
    55  }
    56  
    57  func main() {
    58  	var dir string
    59  	var rootCmd = &cobra.Command{
    60  		ValidArgs: []string{"markdown", "man", "rst"},
    61  		Args:      cobra.ExactArgs(1),
    62  		Use:       "makeDocs {markdown | man | rst}",
    63  		Short:     "Generates Singularity documentation",
    64  		Run: func(cmd *cobra.Command, args []string) {
    65  			switch args[0] {
    66  			case "markdown":
    67  				markdownDocs(dir)
    68  			case "man":
    69  				manDocs(dir)
    70  			case "rst":
    71  				rstDocs(dir)
    72  			default:
    73  				sylog.Fatalf("Invalid output type %s\n", args[0])
    74  			}
    75  		},
    76  	}
    77  	rootCmd.Flags().StringVarP(&dir, "dir", "d", ".", "Directory in which to put the generated documentation")
    78  	rootCmd.Execute()
    79  }