[mynewt-newt] branch master updated: Add newt docs command to automatically build the contents of documentation repos

[ut...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

utzig pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-newt.git


The following commit(s) were added to refs/heads/master by this push:
     new ed78ee4  Add newt docs command to automatically build the contents of documentation repos
ed78ee4 is described below

commit ed78ee4430c6e7deb570e0086bfa5a14b68a6f21
Author: Sterling Hughes <st...@runtime.io>
AuthorDate: Sat Mar 16 15:58:29 2019 -0700

    Add newt docs command to automatically build the contents of documentation repos
---
 newt/cli/docs_cmds.go    |  60 ++++++++++++++++++++
 newt/docs/docsbuilder.go | 145 +++++++++++++++++++++++++++++++++++++++++++++++
 newt/newt.go             |   1 +
 util/util.go             |  15 +++++
 4 files changed, 221 insertions(+)

diff --git a/newt/cli/docs_cmds.go b/newt/cli/docs_cmds.go
new file mode 100644
index 0000000..9950a53
--- /dev/null
+++ b/newt/cli/docs_cmds.go
@@ -0,0 +1,60 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package cli
+
+import (
+	"os"
+
+	"github.com/spf13/cobra"
+	"mynewt.apache.org/newt/newt/docs"
+)
+
+func docsBuildRunCmd(cmd *cobra.Command, args []string) {
+	wd, _ := os.Getwd()
+	db, _ := docs.NewDocsBuilder()
+	db.Build(wd + "/_build")
+}
+
+func AddDocsCommands(cmd *cobra.Command) {
+	docsCmdHelpText := ""
+	docsCmdHelpEx := ""
+	docsCmd := &cobra.Command{
+		Use:     "docs",
+		Short:   "Project documentation generation commands",
+		Long:    docsCmdHelpText,
+		Example: docsCmdHelpEx,
+		Run: func(cmd *cobra.Command, args []string) {
+			cmd.Usage()
+		},
+	}
+
+	cmd.AddCommand(docsCmd)
+
+	buildShortHelp := "Generate project documentation using Mynewt docs system."
+
+	buildCmd := &cobra.Command{
+		Use:   "build [<outdir>]",
+		Short: buildShortHelp,
+		Long:  buildShortHelp,
+		Run:   docsBuildRunCmd,
+	}
+
+	docsCmd.AddCommand(buildCmd)
+}
diff --git a/newt/docs/docsbuilder.go b/newt/docs/docsbuilder.go
new file mode 100644
index 0000000..b869e63
--- /dev/null
+++ b/newt/docs/docsbuilder.go
@@ -0,0 +1,145 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package docs
+
+import (
+	"fmt"
+	"io/ioutil"
+	"os"
+
+	"mynewt.apache.org/newt/newt/project"
+	"mynewt.apache.org/newt/util"
+)
+
+type DocsBuilder struct {
+	project *project.Project
+}
+
+type DocDescriptor struct {
+	path    string
+	name    string
+	isLocal bool
+}
+
+func NewDocsBuilder() (*DocsBuilder, error) {
+	db := &DocsBuilder{}
+	db.project = project.GetProject()
+
+	return db, nil
+}
+
+func (db *DocsBuilder) GetDocs() ([]*DocDescriptor, error) {
+	docs := []*DocDescriptor{}
+
+	for _, repo := range db.project.Repos() {
+		name := repo.Name()
+
+		if repo.IsLocal() {
+			name = db.project.Name()
+		}
+		fmt.Println(name)
+
+		descriptor := &DocDescriptor{
+			path:    repo.Path() + "/docs",
+			name:    name,
+			isLocal: repo.IsLocal(),
+		}
+
+		docs = append(docs, descriptor)
+	}
+
+	return docs, nil
+}
+
+func (db *DocsBuilder) generateDoxygen(doc *DocDescriptor, tmpdir string) error {
+	util.StatusMessage(util.VERBOSITY_DEFAULT,
+		"Preparing docs, running doxygen in %s\n", doc.path)
+
+	util.CallInDir(doc.path, func() error {
+		// Run doxygen
+		doxygenGenerate := []string{
+			"doxygen",
+			"doxygen.xml",
+		}
+
+		util.ShellCommand(doxygenGenerate, nil)
+
+		return nil
+	})
+
+	util.MoveDir(doc.path+"/_gen/_xml", tmpdir+"/"+doc.name+"-xml")
+	os.RemoveAll(doc.path + "/_gen")
+
+	return nil
+}
+
+func (db *DocsBuilder) Build(outdir string) error {
+	// Get this project's base directory, plus all of the repo directories
+	// and copy them to the scratch directory
+	// Then run & generate build.
+	docs, _ := db.GetDocs()
+
+	tmpdir, _ := ioutil.TempDir("", "docs-repo")
+
+	// Copy the docs into the generation directory one by one.
+	for _, doc := range docs {
+		if util.NodeNotExist(doc.path) {
+			continue
+		}
+
+		if util.NodeExist(doc.path + "/doxygen.xml") {
+			db.generateDoxygen(doc, tmpdir)
+		}
+
+		tmpPath := tmpdir + "/"
+		if !doc.isLocal {
+			tmpPath = tmpPath + doc.name
+		}
+
+		util.StatusMessage(util.VERBOSITY_DEFAULT,
+			"Preparing docs, copying docs directory %s to %s\n", doc.path,
+			tmpPath)
+
+		util.CopyDir(doc.path, tmpPath)
+	}
+
+	// Change into the temporary directory to build it.
+	util.StatusMessage(util.VERBOSITY_DEFAULT,
+		"Generating documentation in %s placing results in %s\n", tmpdir, outdir)
+
+	util.CallInDir(tmpdir, func() error {
+		// Time to run the build!
+		sphinxBuild := []string{
+			"sphinx-build",
+			"-j", "auto",
+			tmpdir,
+			outdir,
+		}
+
+		util.ShellCommand(sphinxBuild, nil)
+		return nil
+	})
+
+	util.StatusMessage(util.VERBOSITY_DEFAULT,
+		"Cleaning up result of generated documentation\n")
+	os.RemoveAll(tmpdir)
+
+	return nil
+}
diff --git a/newt/newt.go b/newt/newt.go
index 4a4453c..d277645 100644
--- a/newt/newt.go
+++ b/newt/newt.go
@@ -162,6 +162,7 @@ func main() {
 	cli.AddTargetCommands(cmd)
 	cli.AddValsCommands(cmd)
 	cli.AddMfgCommands(cmd)
+	cli.AddDocsCommands(cmd)
 
 	/* only pass the first two args to check for complete command */
 	if len(os.Args) > 2 {
diff --git a/util/util.go b/util/util.go
index 31008f9..4318b82 100644
--- a/util/util.go
+++ b/util/util.go
@@ -503,6 +503,21 @@ func MoveDir(srcDir string, destDir string) error {
 	return nil
 }
 
+func CallInDir(path string, execFunc func() error) error {
+	wd, err := os.Getwd()
+	if err != nil {
+		return err
+	}
+
+	os.Chdir(path)
+
+	err = execFunc()
+
+	os.Chdir(wd)
+
+	return err
+}
+
 // Reads each line from the specified text file into an array of strings.  If a
 // line ends with a backslash, it is concatenated with the following line.
 func ReadLines(path string) ([]string, error) {