diff --git a/.gitignore b/.gitignore index ecb193d..42d2cb2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,3 @@ aquila # .idea files .idea - - -aquila.yaml \ No newline at end of file diff --git a/README.md b/README.md index b899d26..86db1d4 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ Manage Docs Seamlessly. Aquila Helps you to manage testable code snippets in you ## Usage -See Usage Instructions. +See Usage Instructions [here](how_to_use.md), and also see the [example](example/). -Building from Source : +### Building from Source : ```bash git clone git@github.com:amanv8060/aquila.git diff --git a/cmd/generate.go b/cmd/generate.go index 0e59075..c677654 100644 --- a/cmd/generate.go +++ b/cmd/generate.go @@ -18,13 +18,13 @@ import ( // generateCmd represents the generate command var generateCmd = &cobra.Command{ Use: "generate", - Short: "A brief description of your command", - Long: `A longer description that spans multiple lines and likely contains examples -and usage of using your command. For example: + Short: "Generate code regions from your codebase.", + Long: `Generate command generates code regions from your codebase. -Cobra is a CLI library for Go that empowers applications. -This application is a tool to generate the needed files -to quickly create a Cobra application.`, +It will generate code regions from a given codebase and store them in a directory called code_regions within a path +specified by the user through config file. The code regions are stored in a JSON file with the name of the file as +the key and the value being an array of strings containing the code region. +`, Run: func(cmd *cobra.Command, args []string) { codePath := viper.GetString("codePath") // recursively get all files path in the codePaths diff --git a/cmd/root.go b/cmd/root.go index 8684a54..2ecbc94 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -33,7 +33,7 @@ var cfgFile string // rootCmd represents the base command when called without any subcommands var rootCmd = &cobra.Command{ Use: "aquila", - Short: "A brief description of your application", + Short: "Aquila is a tool to manage your docs seamlessly.", Long: rootCommandHeader, } diff --git a/cmd/updatemd.go b/cmd/updatemd.go index 2dd5561..1d2ca5c 100644 --- a/cmd/updatemd.go +++ b/cmd/updatemd.go @@ -1,3 +1,9 @@ +/* +Copyright © 2022 Aman Verma. All rights reserved. +Use of this source code is governed by a BSD-style +license that can be found in the LICENSE file. +*/ + package cmd import ( @@ -5,11 +11,17 @@ import ( "github.com/spf13/cobra" ) -// generateCmd represents the generate command +// updateMdCmd represents the generate command var updateMdCmd = &cobra.Command{ Use: "update-md", Short: "Update Annotated Regions in your markdown with code regions", - Long: `Updates the annotated regions in your markdown with the code regions.`, + Long: `Updates the annotated regions in your markdown with the code regions. + +It will update the annotated regions in your markdown with the code regions from the code_regions directory. +It works on insert-or-replace basis. If the annotated region is not present in the markdown, it will be inserted. +If the annotated region has a code region present in the markdown, it will be replaced with the newly generated code +region. +`, Run: func(cmd *cobra.Command, args []string) { utils.UpdateRegions() }, diff --git a/code_regions/main.go.json b/code_regions/main.go.json deleted file mode 100755 index 1a96803..0000000 --- a/code_regions/main.go.json +++ /dev/null @@ -1 +0,0 @@ -{"imports":["import \"aquila/cmd\"","\t..."],"main":["func main() {","\tcmd.Execute()","}","\t..."]} \ No newline at end of file diff --git a/docs/test.md b/docs/test.md deleted file mode 100644 index 4b96de5..0000000 --- a/docs/test.md +++ /dev/null @@ -1,19 +0,0 @@ -This is a dummy Markdown - -Snippet 1 - - -```go -func main() { - cmd.Execute() -} - ... -``` - -Some dummy text - -Some dummy text - -Some dummy text - -Some dummy text diff --git a/example/.gitignore b/example/.gitignore new file mode 100644 index 0000000..4c71538 --- /dev/null +++ b/example/.gitignore @@ -0,0 +1,2 @@ +# Ignore Code Regions if you don't want to be source controlled. +code_regions/ \ No newline at end of file diff --git a/example/aquila.yaml b/example/aquila.yaml new file mode 100644 index 0000000..cd85ed0 --- /dev/null +++ b/example/aquila.yaml @@ -0,0 +1,2 @@ +codePath: "." +docsPath: "./docs" \ No newline at end of file diff --git a/example/docs/Getting_Started(original).md b/example/docs/Getting_Started(original).md new file mode 100644 index 0000000..d8fe6b1 --- /dev/null +++ b/example/docs/Getting_Started(original).md @@ -0,0 +1,21 @@ +## Getting Started + +This is a simple example of how to use the `example` package. + +### Installation + +Clone the repo and cd into the directory: + + git clone + cd example + +## Example Functions : + +### How to say Hi + +`` + +### How to add in js + +`` + diff --git a/example/docs/Getting_Started.md b/example/docs/Getting_Started.md new file mode 100644 index 0000000..43dc7ec --- /dev/null +++ b/example/docs/Getting_Started.md @@ -0,0 +1,36 @@ +## Getting Started + +This is a simple example of how to use the `example` package. + +### Installation + +Clone the repo and cd into the directory: + + git clone + cd example + +## Example Functions : + +### How to say Hi + + +```js + +// Function to say hi. +function sayHi() { + console.log("Hi!"); +} + ... +``` + +### How to add in js + + +```js + +function addition(a, b) { + return a + b; +} + ... +``` + diff --git a/example/main.js b/example/main.js new file mode 100644 index 0000000..8c98a40 --- /dev/null +++ b/example/main.js @@ -0,0 +1,18 @@ +// #aqstart sayHi + +// Function to say hi. +function sayHi() { + console.log("Hi!"); +} + +// #aqend sayHi + + +// #aqstart addition + +function addition(a, b) { + return a + b; +} + +// #aqend addition + diff --git a/example/package.json b/example/package.json new file mode 100644 index 0000000..561eafc --- /dev/null +++ b/example/package.json @@ -0,0 +1,11 @@ +{ + "name": "example_code_repo", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC" +} diff --git a/how_to_use.md b/how_to_use.md new file mode 100644 index 0000000..bbfa5c4 --- /dev/null +++ b/how_to_use.md @@ -0,0 +1,24 @@ +## How to Use + +Using aquila is a 3-step process: + +### Setup Config Files + +- Create `aquila.yaml` config file. +- Specify the `codePath` & `docsPath` directory in the config file. + +### Setting Up + +- Annotate all the code regions that might be used within the docs using a comment `#aqstart ` + and closing it with `#aqend `. +- Wherever you want to use the code region in the docs, use the following + syntax: ` region=""?>`. + +### Using + +- Generate the docs using `aquila generate` command. +- The generated docs will be present in the `./code_regions` directory. +- Run `aquila update-md` to update the docs with the generated code regions. + +Example can be found [here](example/). + diff --git a/main.go b/main.go index f4eadfe..7e362ff 100644 --- a/main.go +++ b/main.go @@ -6,14 +6,8 @@ license that can be found in the LICENSE file. package main -// #aqstart imports import "aquila/cmd" -// #aqend imports - -// #aqstart main func main() { cmd.Execute() } - -// #aqend main diff --git a/models/codeRegion.go b/models/codeRegion.go index a93a350..7f68316 100644 --- a/models/codeRegion.go +++ b/models/codeRegion.go @@ -1,3 +1,9 @@ +/* +Copyright © 2022 Aman Verma. All rights reserved. +Use of this source code is governed by a BSD-style +license that can be found in the LICENSE file. +*/ + package models import "regexp" diff --git a/utils/updateRegions.go b/utils/updateRegions.go index de7c238..21747f9 100644 --- a/utils/updateRegions.go +++ b/utils/updateRegions.go @@ -1,3 +1,9 @@ +/* +Copyright © 2022 Aman Verma. All rights reserved. +Use of this source code is governed by a BSD-style +license that can be found in the LICENSE file. +*/ + package utils import (