chore: transfer docs on module configuration (a subset of the module docs)

for-developers/git-workflows/git-crashcourse.md

@@ -11,6 +11,14 @@ For first-time Git and GitHub users, contributing to open source can feel overwh
 
 Companion is open source—anyone can view and modify the code. While you're free to customize it for your own use, maintaining software quality requires coordination. Git and GitHub are the tools we use to make this possible: GitHub hosts the source code and metadata, while Git manages version control and transfers code between repositories.
 
+:::tip
+
+1. A GUI front-end such as SmartGit, GitGUI, can greatly simplify the overall process. See the tip under [Installing Git](installing-git#install-git) for our recommendations.
+
+2. The instructions on this page describe how to contribute to repositories for which you don't have write permission, which is typically the case when you're contributing to an existing repository. Eventually you may get write-access, for example if you become the maintainer of a Companion module, in which case the flow can be simplified...but it's still good practice to develop new features on a new branch.
+
+:::
+
 ## The Fork and Clone Workflow
 
 ### Why You Can't Edit Directly

for-developers/git-workflows/github-workflow.md

@@ -9,9 +9,14 @@ description: Introduction to git and github workflow for beginners
 
 The following is the basic workflow for contributing to Companion (and many other open-source repositories) on GitHub. The order of operations is a key to keeping everything straight... This page assumes basic knowledge of Git and GitHub. To learn Git, check out our [Git Crashcourse](git-crashcourse), or [Git's documentation](https://git-scm.com/learn) or the many online resources.
 
+The examples below use the core Companion repo, bitfocus/companion, for specificity. If you are contributing to a module, substitute the module's repository name for bitfocus/companion. (For example, bitfocus/companion-module-generic-http.)
+
 :::tip
-A GUI front-end such as SmartGit, GitGUI, can greatly simplify the overall process. See the tip under [Installing Git](installing-git#install-git) for our recommendations.
-:::
+
+1. A GUI front-end such as SmartGit, GitGUI, can greatly simplify the overall process. See the tip under [Installing Git](installing-git#install-git) for our recommendations.
+
+2. The instructions on this page describe how to contribute to repositories for which you don't have write permission, which is typically the case when you're contributing to an existing repository. Eventually you may get write-access, for example if you become the maintainer of a Companion module, in which case the flow can be simplified...but it's still good practice to develop new features on a new branch.
+   :::
 
 :::note[Expert Note]
 The following outline names the bitfocus remote "origin" and your remote fork "personal". This seems much clearer than the convention of naming the bitfocus repo "upstream" and your remote fork "origin" (which it is not!). The convention recommended here eliminates a step and also ensures that your pulls come from the Bitfocus repo. Many thanks to Brian Teeman for this and other suggestions.
@@ -27,6 +32,8 @@ If you are cloning to a Windows computer be sure to [configure git line-endings
 git clone https://github.com/bitfocus/companion.git
 ```
 
+(module developers: substitute the appropriate GitHub location.)
+
 :::note
 The Bitfocus repository is read-only for most users. In the next step we will create a writeable "fork" of the Bitfocus repo that will be used for sending in proposed code changes (PRs)
 :::
@@ -35,15 +42,15 @@ The Bitfocus repository is read-only for most users. In the next step we will cr
 
 ## 1b. Fork Companion to your GitHub account
 
-Back on the [Companion Website](https://github.com/bitfocus/companion), click on the `Fork` button in the Code tab. This will create a repository under your Github account that you can write to.
+Back on the [Companion GitHub page](https://github.com/bitfocus/companion) or the module's GitHub page, click on the `Fork` button in the Code tab. This will create a repository under your Github account that you can write to.
 
 **updating**: Once the fork has been created, use the "Sync Fork" button in GitHub to keep it up-to-date.
 
 ### Add the fork as a remote to your local repository
 
 Your local repository will need two "know" two remote (GitHub) repos -- one for keeping in sync with Bitfocus and the other for writing your code changes. We suggest naming this second one "personal" for clarity -- it is your personal fork of companion _on GitHub_:
 
-On the GitHub page for your new fork, copy the HTTPS link to your fork using the green <span style={{background: "#00CC00", borderRadius: "5px"}}> **&lt;&gt;Code** </span> button. Then paste it on a line starting with `it remote add personal`. It should look like this:
+On the GitHub page for your new fork, copy the HTTPS link to your fork using the green <span style={{background: "#00CC00", borderRadius: "5px", fontSize: "0.8em", padding: "0.5em"}}> **&lt;&gt; Code &#x25BC;** </span> button. Then paste it on a line starting with `it remote add personal`. It should look like this (for core Companion):
 
 ```bash
 git remote add personal https://github.com/<your username>/companion.git
@@ -52,7 +59,7 @@ git remote add personal https://github.com/<your username>/companion.git
 (In a GUI frontend you would select "Add Remote..." from a menu. SmartGit, for example, will automatically pick up the URL from your clipboard when you do this.)
 
 :::note
-By default, the Bitfocus remote that was cloned above, was named "origin". So "origin" refers to Bitfocus (the "origin" of your clone) and "personal" refers to your fork on GitHub.
+By default, the Bitfocus remote that you cloned above, was named "origin". So "origin" refers to Bitfocus (the "origin" of your clone) and "personal" refers to your fork on GitHub.
 :::
 
 ## 2. Create a new branch in your local repo
@@ -61,7 +68,7 @@ By default, the Bitfocus remote that was cloned above, was named "origin". So "o
 git switch -c <new-branch-name>
 ```
 
-This creates and checks out the new branch.
+(In a GUI frontend you would select "Add Branch..." from a menu.) This creates and checks out the new branch.
 
 Next, modify/add code for your feature of bug-fix using your favorite coding tools.
 
@@ -71,15 +78,15 @@ When you are satisfied with some or all of your changes, commit them to the new
 git commit -m 'message'
 ```
 
-This is where you really want to be using a GUI front-end to git for managing you repo!
+This is where you really want to be using a GUI front-end to git to keep track of everything!
 
 ## 3. Push the branch to your GitHub fork
 
 ```bash
 git push -u personal <your_branch>
 ```
 
-After the first push, you can push further commits on that branch using just `git push`
+(In a GUI frontend you would select "Push to..." from a menu and select "personal".) After the first push, you can push further commits on that branch using just `git push`
 
 ## 4. Submit a Pull Request (PR) to Bitfocus
 

for-developers/module-development/home.md

@@ -6,13 +6,14 @@ description: Developer environment setup specific to module development.
 ---
 
 So, you want to develop a module for Companion? Welcome!
-This section describes what you need to know and do to make a beautiful module to control your favorite gear with Companion.
+
+Companion uses plug-ins to expand its capabilities, we call these plug-ins "modules". For every device you can control with Companion there is a "module" that manages the connection. This page describes how to set up your computer for developing Companion modules. Subsequent pages will provide details on the contents   of the module and its lifecycle.
 
 ## Prerequisites
 
 Before you start, make sure you have [Installed the Development Tools](../setting-up-developer-environment.md) and familiarized yourself with [Git Workflows](../git-workflows/git-crashcourse.md).
 
-This page discusses additional setup needed in order to develop or contribute to Companion modules.
+This page discusses additional setup specific to Companion modules.
 
 ## Install Companion
 
@@ -21,44 +22,61 @@ You can develop modules against any standard release or beta build of Companion.
 Download and install a recent version from [the website](https://bitfocus.io/user/downloads)
 
 :::tip
-Starting with Companion v4.0, the module release cycle has been separated from the Companion release cycle: The timing of module version releases are determined by the module developer independently of the Companion releases.
+Starting with Companion v4.0, the module release cycle has been decoupled from the Companion release cycle: The timing of module version releases are determined by the module developer independently of the Companion releases.
 
 We therefore recommend developing your module using the current stable version to ensure that users will be able to use your module right away instead of having to wait until the current beta is released.
 :::
 
-## Set up Companion for Module Development
+## Set up the Development Folder
 
-Follow the instructions in [Setting up a Development Folder](./local-modules.md) to create the folders and to setup Companion for module development. Briefly:
+- Create a modules development folder somewhere on your computer. You can call it whatever you like.
+- Open the companion launcher and click the cog in the top right. In versions prior to v4.1 this will reveal a 'Developer modules path' field. Starting in Companion v4.1 it will open up a settings window in which you can set the path. Set it to the development folder you just created.
 
-- Create a `companion-module-dev` folder somewhere on your computer. You can call it whatever you like.
-- Once you have the companion launcher open, click the cog in the top right. In versions prior to v4.1 this will reveal a 'Developer modules path' field. Starting in v4.1 it will open up a settings window in which you can set the path. Set it to the `companion-module-dev` folder you created earlier.
+Please see the next page: [Setting up a Dev Folder](./local-modules.md) for full details.
 
 :::tip
-Companion will load any modules it finds in subfolders of that folder.
 
-When files inside those folders is changed, Companion will automatically restart any connections using that module.
+Companion will load any modules that are in _subfolders_ of the modules development folder.
+However, starting with v4.0, note that **your new dev module will show up in the Connections page** but not in the Modules page, since it is not yet part of the official set of Companion modules.
+
 :::
 
-## Clone the module
+## Clone or Copy a module from GitHub
+
+With over 700 published modules, you may find a module already written for you device. You can find the GitHub repository for each module by searching [Bitfocus in GitHub](https://github.com/bitfocus).
+
+- If you want to **contribute to an existing module**, clone it to your development folder using your [preferred git tool](../git-workflows/installing-git.md). (See [Git Crash Course](../git-workflows/git-crashcourse.md) and [The GitHub Workflow](../git-workflows/github-workflow.md) for important details).
+- If you are **writing a new module**, then download and expand the zip file for the [TypeScript template module](https://github.com/bitfocus/companion-module-template-ts/archive/refs/heads/main.zip) into the module development folder (see the next section on naming your module). If you prefer, you can clone the [template repo](https://github.com/bitfocus/companion-module-template-ts), but remember to delete the remote link (`git remote remove origin`) before continuing. We encourage you to use Typescript for all new modules but acknowledge that it isn't for everyone, so we fully support [Javascript](https://github.com/bitfocus/companion-module-template-js) too!
+- Alternatively for a new module, you can start by downloading the zip or cloning a module that controls a device similar to yours -- both options can be found under the the green <span style={{background: "#00CC00", borderRadius: "5px", fontSize: "0.8em", padding: "0.5em"}}> **&lt;&gt; Code &#x25BC;** </span> button for that module's GitHub repo. Beware: by using another module as a base, you could inherit some subtle misconfigurations or deviations they have made from our recommendations. As with using the template, if you cloned the repo be sure to remove the remote connection by running `git remote remove origin`, since you will be creating a new module rather than modifying the existing one.
+
+### Additional steps for new modules
+
+1. Rename your module's directory _companion-module-mymanufacturer-myproduct_, replacing _mymanufacturer-myproduct_ with appropriate names. Try to think of what is most appropriate for your device: Are there other similar devices by the manufacturer that use the same protocol that the module could support later on? If so try and name it to more easily allow for that.
+
+2. In at least _package.json_, _companion/manifest.json_ and _companion/HELP.md_, edit the name and description of the module to match what yours is called. The search feature in your IDE is really helpful to find all of the places the name shows up! See the [Module Configuration section](./module-config/file-structure.md) and especially the [documentation for the manifest.json file](./module-config/manifest.json.md) for further details.
+
+3. Please see [Module Configuration](./module-config/file-structure.md) and the other pages in that section for more details and more options on starting your own module.
+
+## Install the dependencies
+
+In a shell inside the new folder, run the following:
+
+1. `yarn install` This will install any dependencies needed by the module.
+
+:::tip
 
-- If you are working on an existing module, clone it inside this folder using your preferred git tool.
-- If you are making a new module, then clone the template module, available in [TypeScript](https://github.com/bitfocus/companion-module-template-ts) or [Javascript](https://github.com/bitfocus/companion-module-template-js), to an appropriately named folder inside of `companion-module-dev`. If you are starting a new module we encourage you to use Typescript but acknowledge that it isn't for everyone, so fully support Javascript too!
+If you are using an IDE such as [VS Code](https://code.visualstudio.com/), make the clone your current project (i.e., open the repository folder), then open a terminal (shell) inside the IDE to ensure you are running  yarn in the correct folder.
 
-:::note
-Starting with v4.0, note that **your new dev module will show up in the Connections page** but not in the Modules page, since it is not yet part of the official set of Companion modules.
 :::
 
 ## Start working on your module
 
-You are now ready to start developing your module.
+You are now ready to start developing your module. Here are our suggested next steps:
 
-You should notice that whenever you save a file inside your `companion-module-dev` folder, companion will restart itself.  
-If it does not, or you are having issues getting your module to load in then please reach out on slack and we will be happy to assist you in getting started.
+- Familiarize yourself with the [Module Configuration](module-config/file-structure.md) to understand the general file structure and configuration options, especially if working on a new module.
+- Read [Module development 101](./module-development-101.md) for an overview of the development lifecycle.
+- Review the recommended [GitHub Workflow](../git-workflows/github-workflow.md) to learn best practices for new features to your codebase.
 
-## Further Reading
+You can develop code while the module is running in Companion: whenever you save a file inside your module development folder, Companion will automatically restart any connections using that module.
 
-- [Module development 101](./module-development-101.md)
-- [Creating a module](https://github.com/bitfocus/companion-module-base/wiki/Creating-a-module)
-- [Actions](https://github.com/bitfocus/companion-module-base/wiki/Actions)
-- [Feedbacks](https://github.com/bitfocus/companion-module-base/wiki/Feedbacks)
-- [Variables](https://github.com/bitfocus/companion-module-base/wiki/Variables)
+If it does not, or you are having issues getting your module to load in then please reach out on [Slack](https://bfoc.us/ke7e9dqgaz) and we will be happy to assist you in getting started.

for-developers/module-development/local-modules.md

@@ -1,8 +1,8 @@
 ---
 title: Setting up the Development Folder
-sidebar_label: Setting a Dev Folder
+sidebar_label: '└─ Setting up a Dev Folder'
 sidebar_position: 2
-description: How to load modules during module development.
+description: How to load modules in Companion during module development.
 ---
 
 Starting with Companion 3.0 you can develop, test and use your own module code without the need for the Core Companion development environment. Here is how you do it.
@@ -34,7 +34,7 @@ Inside of this folder should be one or more folders that use the following layou
 - Make sure **Enable Developer Modules** is switched on. You can now close the window
 - Click on "Launch GUI" to open the Admin interface. In the connections list you should find the connection provided by the developer module. If the developer module is using the same internal ID as a module that is distributed with Companion, be sure to choose the "dev" version in the configuration.  
   If you don't see the developers module, please check the log and switch on debug, maybe the module has crashed.
-- You can replace a developers module or files within it while Companion is running. Companion will detect the change and restart only that module without affecting other modules.
+- You can replace a developers module or files within it while Companion is running. Companion will detect the change and restart only that module without affecting other modules. You can also force a module to reload by disabling and re-enabling a connection.
 
 :::note
 
@@ -56,13 +56,11 @@ the **Developer Module Path** is _**mydev**_ and not _mydev/module1_.
 
 ## Headless development
 
-- If you are running Companion from source in development mode, there is a folder `module-local-dev` inside the repository that gets read for your modules.
-- It follows the same rules for structuring as above.
-- Any changes made to the contents of the folder will cause the affected modules to be reloaded. You can force them to reload by disabling and re-enabling a connection.
-
+- If you are running Companion from source in development mode, there is a folder `module-local-dev` inside the repository that gets read for your modules. It follows the same rules for structuring as above.
 - You can also use the command-line argument `--extra-module-path` to specify the dev folder.
 - Alternatively, you can set the environment variable `COMPANION_DEV_MODULES` to the dev folder. For your convenience, you can put the following in `.env` in your companion source folder:
 
 ```
 COMPANION_DEV_MODULES=<dev modules path>
 ```
+

for-developers/module-development/module-config/_category_.json

@@ -0,0 +1,11 @@
+{
+	"label": "Module Configuration",
+	"position": 10,
+	"link": {
+		"type": "generated-index",
+		"title": "Configuring your companion module"
+	},
+	"customProps": {
+		"description": "The files and file structure necessary to configure a module repository."
+	}
+}