modulegen: create internal/mkdocs (#1504)

* modulegen: create internal/mkdocs

Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>

* Apply suggestions from code review

Co-authored-by: Manuel de la Peña <social.mdelapenya@gmail.com>

---------

Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>
Co-authored-by: Manuel de la Peña <social.mdelapenya@gmail.com>

modulegen/context.go

@@ -45,6 +45,25 @@ func (ctx *Context) getModulesByBaseDir(baseDir string) ([]string, error) {
 	return dirs, nil
 }
 
+func (ctx *Context) getMarkdownsFromDir(baseDir string) ([]string, error) {
+	dir := filepath.Join(ctx.DocsDir(), baseDir)
+
+	allFiles, err := os.ReadDir(dir)
+	if err != nil {
+		return nil, err
+	}
+
+	dirs := make([]string, 0)
+
+	for _, f := range allFiles {
+		if !f.IsDir() && filepath.Ext(f.Name()) == ".md" {
+			dirs = append(dirs, f.Name())
+		}
+	}
+	sort.Strings(dirs)
+	return dirs, nil
+}
+
 func (ctx *Context) GetExamples() ([]string, error) {
 	return ctx.getModulesByBaseDir("examples")
 }
@@ -53,6 +72,18 @@ func (ctx *Context) GetModules() ([]string, error) {
 	return ctx.getModulesByBaseDir("modules")
 }
 
+func (ctx *Context) GetExamplesDocs() ([]string, error) {
+	return ctx.getMarkdownsFromDir("examples")
+}
+
+func (ctx *Context) GetModulesDocs() ([]string, error) {
+	return ctx.getMarkdownsFromDir("modules")
+}
+
 func (ctx *Context) MkdocsConfigFile() string {
 	return filepath.Join(ctx.RootDir, "mkdocs.yml")
 }
+
+func NewContext(dir string) *Context {
+	return &Context{RootDir: dir}
+}

modulegen/context_test.go

@@ -1,4 +1,4 @@
-package main_test
+package main
 
 import (
 	"os"
@@ -9,14 +9,11 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	main "github.com/testcontainers/testcontainers-go/modulegen"
 	"github.com/testcontainers/testcontainers-go/modulegen/internal/dependabot"
 )
 
 func TestGetDependabotConfigFile(t *testing.T) {
-	tmp := t.TempDir()
-
-	ctx := &main.Context{RootDir: filepath.Join(tmp, "testcontainers-go")}
+	ctx := NewContext(filepath.Join(t.TempDir(), "testcontainers-go"))
 
 	githubDir := ctx.GithubDir()
 	cfgFile := ctx.DependabotConfigFile()
@@ -33,9 +30,7 @@ func TestGetDependabotConfigFile(t *testing.T) {
 }
 
 func TestExamplesHasDependabotEntry(t *testing.T) {
-	rootDir, err := getRootDir()
-	require.NoError(t, err)
-	ctx := &main.Context{RootDir: rootDir}
+	ctx := getRootContext(t)
 	examples, err := ctx.GetExamples()
 	require.NoError(t, err)
 	dependabotUpdates, err := dependabot.GetUpdates(ctx.DependabotConfigFile())
@@ -69,9 +64,7 @@ func TestExamplesHasDependabotEntry(t *testing.T) {
 }
 
 func TestModulesHasDependabotEntry(t *testing.T) {
-	rootDir, err := getRootDir()
-	require.NoError(t, err)
-	ctx := &main.Context{RootDir: rootDir}
+	ctx := getRootContext(t)
 	modules, err := ctx.GetModules()
 	require.NoError(t, err)
 	dependabotUpdates, err := dependabot.GetUpdates(ctx.DependabotConfigFile())
@@ -102,12 +95,3 @@ func TestModulesHasDependabotEntry(t *testing.T) {
 		assert.True(t, found, "module %s is not present in the dependabot updates", module)
 	}
 }
-
-func getRootDir() (string, error) {
-	current, err := os.Getwd()
-	if err != nil {
-		return "", err
-	}
-
-	return filepath.Dir(current), nil
-}

modulegen/go.mod

@@ -4,6 +4,7 @@ go 1.20
 
 require (
 	github.com/stretchr/testify v1.8.4
+	golang.org/x/exp v0.0.0-20230811145659-89c5cff77bcb
 	golang.org/x/text v0.12.0
 	gopkg.in/yaml.v3 v3.0.1
 )

modulegen/go.sum

@@ -4,6 +4,8 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+golang.org/x/exp v0.0.0-20230811145659-89c5cff77bcb h1:mIKbk8weKhSeLH2GmUTrvx8CjkyJmnU1wFmg59CUjFA=
+golang.org/x/exp v0.0.0-20230811145659-89c5cff77bcb/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc=
 golang.org/x/text v0.12.0 h1:k+n5B8goJNdU7hSvEtMUz3d1Q6D/XW4COJSJR6fN0mc=
 golang.org/x/text v0.12.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=

modulegen/internal/mkdocs/main.go

@@ -0,0 +1,18 @@
+package mkdocs
+
+func UpdateConfig(configFile string, isModule bool, exampleMd string, indexMd string) error {
+	config, err := ReadConfig(configFile)
+	if err != nil {
+		return err
+	}
+	config.addExample(isModule, exampleMd, indexMd)
+	return writeConfig(configFile, config)
+}
+
+func CopyConfig(configFile string, tmpFile string) error {
+	config, err := ReadConfig(configFile)
+	if err != nil {
+		return err
+	}
+	return writeConfig(tmpFile, config)
+}

modulegen/internal/mkdocs/reader.go

@@ -0,0 +1,23 @@
+package mkdocs
+
+import (
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+func ReadConfig(configFile string) (*Config, error) {
+	file, err := os.ReadFile(configFile)
+	if err != nil {
+		return nil, err
+	}
+
+	config := &Config{}
+
+	err = yaml.Unmarshal(file, config)
+	if err != nil {
+		return nil, err
+	}
+
+	return config, nil
+}

modulegen/mkdocs.go → modulegen/internal/mkdocs/types.go

@@ -1,13 +1,13 @@
-package main
+package mkdocs
 
 import (
-	"os"
-	"path/filepath"
+	"sort"
+	"strings"
 
-	"gopkg.in/yaml.v3"
+	"golang.org/x/exp/slices"
 )
 
-type MkDocsConfig struct {
+type Config struct {
 	SiteName string   `yaml:"site_name"`
 	SiteURL  string   `yaml:"site_url"`
 	Plugins  []string `yaml:"plugins"`
@@ -44,59 +44,36 @@ type MkDocsConfig struct {
 	} `yaml:"extra"`
 }
 
-func getMkdocsConfigFile(rootDir string) string {
-	return filepath.Join(rootDir, "mkdocs.yml")
-}
-
-func getExamples() ([]os.DirEntry, error) {
-	return getModulesOrExamples(false)
-}
-
-func getExamplesDocs() ([]os.DirEntry, error) {
-	parent, err := getRootDir()
-	if err != nil {
-		return nil, err
-	}
-
-	dir := filepath.Join(parent, "docs", "examples")
-
-	return os.ReadDir(dir)
-}
-
-func getRootDir() (string, error) {
-	current, err := os.Getwd()
-	if err != nil {
-		return "", err
+func (c *Config) addExample(isModule bool, exampleMd string, indexMd string) {
+	mkdocsExamplesNav := c.Nav[4].Examples
+	if isModule {
+		mkdocsExamplesNav = c.Nav[3].Modules
 	}
 
-	return filepath.Dir(current), nil
-}
-
-func readMkdocsConfig(rootDir string) (*MkDocsConfig, error) {
-	configFile := getMkdocsConfigFile(rootDir)
+	if !slices.Contains(mkdocsExamplesNav, exampleMd) {
 
-	file, err := os.ReadFile(configFile)
-	if err != nil {
-		return nil, err
-	}
+		// make sure the index.md is the first element in the list of examples in the nav
+		examplesNav := make([]string, len(mkdocsExamplesNav)-1)
+		j := 0
 
-	config := &MkDocsConfig{}
+		for _, exampleNav := range mkdocsExamplesNav {
+			// filter out the index.md file
+			if !strings.HasSuffix(exampleNav, "index.md") {
+				examplesNav[j] = exampleNav
+				j++
+			}
+		}
 
-	err = yaml.Unmarshal(file, config)
-	if err != nil {
-		return nil, err
-	}
+		examplesNav = append(examplesNav, exampleMd)
+		sort.Strings(examplesNav)
 
-	return config, nil
-}
+		// prepend the index.md file
+		examplesNav = append([]string{indexMd}, examplesNav...)
 
-func writeMkdocsConfig(rootDir string, config *MkDocsConfig) error {
-	data, err := yaml.Marshal(config)
-	if err != nil {
-		return err
+		if isModule {
+			c.Nav[3].Modules = examplesNav
+		} else {
+			c.Nav[4].Examples = examplesNav
+		}
 	}
-
-	file := getMkdocsConfigFile(rootDir)
-
-	return os.WriteFile(file, data, 0o777)
 }

modulegen/internal/mkdocs/writer.go

@@ -0,0 +1,15 @@
+package mkdocs
+
+import (
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+func writeConfig(configFile string, config *Config) error {
+	data, err := yaml.Marshal(config)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(configFile, data, 0o777)
+}