docs: CleanUp and add examples (#6)

.gitignore

@@ -2,6 +2,3 @@ aquila
 
 # .idea files
 .idea
-
-
-aquila.yaml

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 [email protected]:amanv8060/aquila.git

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

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,
 }
 

cmd/updatemd.go

@@ -1,15 +1,27 @@
+/*
+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 (
 	"aquila/utils"
 	"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()
 	},

example/.gitignore

@@ -0,0 +1,2 @@
+# Ignore Code Regions if you don't want to be source controlled.
+code_regions/

example/aquila.yaml

@@ -0,0 +1,2 @@
+codePath: "."
+docsPath: "./docs"

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
+
+`<?code-region "main.js" region="sayHi"?>`
+
+### How to add in js
+
+`<?code-region "main.js" region="addition"?>`
+

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
+
+<?code-region "main.js" region="sayHi"?>
+```js
+
+// Function to say hi.
+function sayHi() {
+    console.log("Hi!");
+}
+	...
+```
+
+### How to add in js
+
+<?code-region "main.js" region="addition"?>
+```js
+
+function addition(a, b) {
+    return a + 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
+

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"
+}

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 <region-name>`
+  and closing it with `#aqend <region-name>`.
+- Wherever you want to use the code region in the docs, use the following
+  syntax: `<?code-region <file-name> region="<region-name>"?>`.
+
+### 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/).
+

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

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"

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 (