chore: transfer docs on modules files (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"}}> **&lt;&gt;Code** </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

@@ -30,35 +30,36 @@ We therefore recommend developing your module using the current stable version t
 
 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 `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.
+- Create a modules development 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 development folder.
 
 :::tip
-Companion will load any modules it finds in subfolders of that folder.
+Companion will load any modules it finds in _subfolders_ of the modules development folder.
 
-When files inside those folders is changed, Companion will automatically restart any connections using that module.
+When files inside those folders are changed, Companion will automatically restart any connections using that module.
 :::
 
 ## Clone the module
 
 - 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 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 the module development folder. 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!
 
 :::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. Check out the information in the [The Module Files](the-module-files/file-structure.md) section to understand the file structure, then proceed to [Module development 101](./module-development-101.md).
 
-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.
+You should notice that whenever you save a file inside your module development 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](https://bfoc.us/ke7e9dqgaz) and we will be happy to assist you in getting started.
 
 ## Further Reading
 
+- [The Module Files](the-module-files/file-structure.md)
 - [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)

for-developers/module-development/module-development-101.md

@@ -1,7 +1,7 @@
 ---
 title: Module Development 101
 sidebar_label: Module Development 101
-sidebar_position: 2
+sidebar_position: 4
 description: The essential overview of Companion module development.
 ---
 
@@ -39,15 +39,15 @@ These other pages will help explain some of the functionality that the module ex
 
 TO-DO: Update links
 
-- [Module Configuration](https://github.com/bitfocus/companion-module-base/wiki/Module-development-101)
+- [Module Configuration](the-module-files/file-structure.md)
 - [Actions](https://github.com/bitfocus/companion-module-base/wiki/Actions)
 - [Feedbacks](https://github.com/bitfocus/companion-module-base/wiki/Feedbacks)
 - [Presets](https://github.com/bitfocus/companion-module-base/wiki/Presets)
 - [Variables](https://github.com/bitfocus/companion-module-base/wiki/Variables)
 
 ## What makes up a module
 
-There are a few files that make up every module. To get an overview of what these are, please see [File Structure](https://github.com/bitfocus/companion-module-base/wiki/File-Structure).
+There are a few files that make up every module. To get an overview of what these are, please see [File Structure](the-module-files/file-structure).
 
 ## The Module source code
 
@@ -75,7 +75,7 @@ Most (so far all) modules do want to provide some interaction with the user. The
 
 TO-DO: Update links
 
-- [Module Configuration](https://github.com/bitfocus/companion-module-base/wiki/Module-development-101)
+- [Module Configuration](the-module-files/file-structure.md)
 - [Actions](https://github.com/bitfocus/companion-module-base/wiki/Actions)
 - [Feedbacks](https://github.com/bitfocus/companion-module-base/wiki/Feedbacks)
 - [Presets](https://github.com/bitfocus/companion-module-base/wiki/Presets)

for-developers/module-development/the-module-files/_category_.json

@@ -0,0 +1,11 @@
+{
+	"label": "The Module Files",
+	"position": 3,
+	"link": {
+		"type": "generated-index",
+		"title": "Understanding the Files in a Companion Module"
+	},
+	"customProps": {
+		"description": "The files and file structure of a module repository."
+	}
+}

for-developers/module-development/the-module-files/code-formatting.md

@@ -0,0 +1,31 @@
+---
+title: 'Formatting Code with Prettier'
+sidebar_label: 'Code Formatting'
+sidebar_position: 3
+description: Enabling prettier to format your code
+---
+
+We recommend setting up code formatting for your module. This helps with the readability of code. It is completely optional.
+
+We use [prettier](https://prettier.io/) to format the Companion code, and you can do the same. `@companion-module/tools` provides a config preset that you can use, but you are also welcome to use your own or a different tool. Be aware that by using a different tool, it will be harder for contributors to format any contributions.
+
+If you are _not_ using the [recommended templates](./file-structure.md), you can configure your module for prettier as follows:
+
+1. Run `yarn add -D prettier` in the root folder of your repo to install it as a dev dependency.
+2. Add the line `"prettier": "@companion-module/tools/.prettierrc.json",` to your _package.json_ file.
+3. You should also add `"format": "prettier -w ."` to the `scripts` block, so that you can run `yarn format` to format all the code
+
+We recommend adding a `.prettierignore` file too, containing:
+
+```
+package.json
+pkg
+```
+
+You can list other files/folders here that should be ignored. We want to ignore package.json as prettier and yarn disagree on how it should be formatted.
+
+:::tip
+
+If you use VS Code, you can install the prettier plugin, and enable 'format on save'. This means you never have to worry about triggering a format as it will be done for you! Many other code editors will have similar plugins available.
+
+:::

for-developers/module-development/the-module-files/code-linting.md

@@ -0,0 +1,110 @@
+---
+title: 'Preventing Common Bugs with ESLint'
+sidebar_label: 'Code Linting'
+sidebar_position: 4
+description: Using a linter to prevent common bugs.
+---
+
+We recommend using [eslint](https://eslint.org/) to lint your code. This can find some easily overlooked but common bugs in your code, among other things.
+
+### @companion-module/tools v2.x
+
+If you are upgrading your config from v1.x, you will need to reconfigure eslint, due to changes in both eslint and how the tools library provides config templates.
+
+Start by removing any existing `.eslintrc.json` or `.eslintrc.cjs`, if they exist.
+
+Then add the needed libraries `yarn add --dev eslint prettier`. If you are using typescript you will also need to `yarn add --dev typescript-eslint`.
+
+Update the `scripts` block in your `package.json` to include:
+
+```js
+"lint:raw": "eslint",
+"lint": "yarn lint:raw ."
+```
+
+You can now run `yarn lint` and see any linter errors. If you need any help understanding the errors or warnings you are given, the eslint docs are really helpful.
+
+A new basic config should be called `eslint.config.mjs`, and could contain:
+
+```js
+import { generateEslintConfig } from '@companion-module/tools/eslint/config.mjs'
+
+export default generateEslintConfig({})
+```
+
+If using typescript, you should specify a `typescriprRoot`
+
+```js
+import { generateEslintConfig } from '@companion-module/tools/eslint/config.mjs'
+
+export default generateEslintConfig({
+	enableTypescript: true,
+})
+```
+
+You can easily override rules in this setup with:
+
+```js
+import { generateEslintConfig } from '@companion-module/tools/eslint/config.mjs'
+
+const baseConfig = await generateEslintConfig({
+	enableTypescript: true,
+})
+
+const customConfig = [
+	...baseConfig,
+
+	{
+		rules: {
+			'n/no-missing-import': 'off',
+			'node/no-unpublished-import': 'off',
+		},
+	},
+]
+
+export default customConfig
+```
+
+Tip: You can set it up so that git runs the linter when you make a commit, so you can be sure that only good code is committed. Take a look at xxxxx for an example of how to setup husky & lint-staged to achieve this.
+
+If you have any suggestions on changes to make to this eslint config, do [open an issue](https://github.com/bitfocus/companion-module-tools/issues) to let us know. We hope that this set of rules will evolve over time based on what is and isnt useful to module developers.
+
+### @companion-module/tools v1.x
+
+To configure it, create a file called `.eslintrc.cjs` with the contents:
+
+```js
+module.exports = require('@companion-module/tools/eslint/index.cjs')({})
+```
+
+Note: This changed in v1.3.0 of `@companion-module/tools`, if you are using an older version you will need to update it first
+
+and to the `scripts` block in your `package.json` add:
+
+```js
+"lint:raw": "eslint --ext .ts --ext .js --ignore-pattern dist --ignore-pattern pkg",
+"lint": "yarn lint:raw ."
+```
+
+You can now run `yarn lint` and see any linter errors. If you need any help understanding the errors or warnings you are given, the eslint docs are really helpful.
+
+There are some options that can be defined to customise the provided configuration:
+
+```js
+module.exports = require('@companion-module/tools/eslint/index.cjs')({
+	// Enable support for jest globals in test files
+	enableJest: false,
+	// Enable support for typescript
+	enableTypescript: false,
+})
+```
+
+You are free to override any rules you wish in your `.eslintrc.cjs`, these steps will give you our recommended (and rather strict) configuration preset.
+
+:::tip
+
+You can set it up so that git runs the linter when you make a commit, so you can be sure that only good code is committed. (I believe this is done in the latest templates?) Take a look at xxxxx for an example of how to setup husky & lint-staged to achieve this.
+
+:::
+
+If you have any suggestions on changes to make to this eslint config, do [open an issue](https://github.com/bitfocus/companion-module-tools/issues) to let us know. We hope that this set of rules will evolve over time based on what is and isnt useful to module developers.