Merge pull request #12 from docsforadobe/add/style-guide

Add contribution style guide

Author: zlovatt

.github/workflows/ci.yml

@@ -32,8 +32,9 @@ jobs:
             mkdocs-material-
       - run: >
           pip install
+          markdown_grid_tables
           mkdocs-exclude-search
-          mkdocs-material
           mkdocs-git-revision-date-localized-plugin
+          mkdocs-material
           mkdocs-print-site-plugin
       - run: mkdocs gh-deploy --force

docs/contributing/contribution-guide.md

@@ -2,69 +2,25 @@
 
 This endeavour is primarily community-supported & run; contributors are welcome and encouraged to suggest fixes, adjustments, notes/warnings, and anything else that may help the project.
 
-This project is written in [Markdown](https://en.wikipedia.org/wiki/Markdown), styled & served using [mkdocs](https://www.mkdocs.org/).
+This project is written in [Markdown](https://en.wikipedia.org/wiki/Markdown), served using [MkDocs](https://www.mkdocs.org/), themed with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
----
-
-## Build HTML Locally
-
-Before pushing to the online project (or submitting a PR), we ask that you develop & test the project locally to ensure the result is what you'd expect.
-
-To build locally:
-
-- Install python & pip
-- From a terminal, navigate to the project directory and run the following command to install dependencies:
-```sh
-pip install -r requirements.txt
-```
-- When done, run the following command to serve the docs:
-```sh
-mkdocs serve
-```
-- Open your browser to the provided url (`http://127.0.0.1:8000`) by default to view the live-updating docs
-
----
-
-## Admonitions Usage
-
-Currently, the following [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) are in use in this project. Try to keep one piece of data per note, for easier parsing.
-
-```
 !!! note
-    Notes detail version added, and/or relevant pieces of information.
+    Broad info on Markdown syntax is outside the scope of this guide. Please familiarise yourself with it before contributing.
 
-!!! tip
-    Tips detail version added, and/or relevant pieces of information.
+---
 
-!!! warning
-    Warnings convey negative behaviours, or when something won't work the way you'd expect.
-```
+## Contributing
 
-These will render as:
+This contribution guide is split into a few chapters.
 
-!!! note
-    Notes detail version added, and/or relevant pieces of information.
+- [To set up your environment & get started with contributing](./getting-set-up.md)
+- [Documentation style](./style-guide.md)
+- [Other tips & tricks](./other-tips.md)
 
 !!! tip
-    Tips detail version added, and/or relevant pieces of information.
-
-!!! warning
-    Warnings convey negative behaviours, or when something won't work the way you'd expect.
-
----
-
-## Adding undocumented attributes or methods
-
-If you find attributes or methods that are not mentioned in this documentation, and they are not publically announced by Adobe, please add this warning to attribute/method so the user knows to use it at their own risk.
-
-```
-!!! warning
-    This method/property is officially undocumented and was found via research. The information here may be inaccurate, and this whole method/property may disappear or stop working some point. Please contribute if you have more information on it!
-```
+    *This repo itself* may not adhere to the standards above, as we're using a number of custom features to help demonstrate best practices.
 
-Rendered as:
-!!! warning
-    This method/property is officially undocumented and was found via research. The information here may be inaccurate, and this whole method/property may disappear or stop working some point. Please contribute if you have more information on it!
+    If in doubt, follow the above guides and templates, *not* the source code of this contribution guide.
 
 ---
 

docs/contributing/getting-set-up.md

@@ -0,0 +1,111 @@
+# Getting Set Up
+
+While it's technically possible to start contributing just through editing the markdown, we ask that you build the project locally to test your changes & ensure the result is what you'd expect.
+
+To start working locally, you'll need to:
+
+1. [Install Python](#install-python)
+2. [Download the repo locally](#download-the-repo-locally)
+3. [Install dependencies](#install-dependencies)
+4. [Build the project](#build-the-project)
+
+??? tip "Quickstart guide"
+
+    Assuming you're familiar with some of the below, here's a quick example way to get set up:
+
+    ```sh
+    # Clone target repo
+    git clone https://github.com/docsforadobe/after-effects-scripting-guide.git
+
+    # Navigate to that directory
+    cd after-effects-scripting-guide
+
+    # Install dependencies
+    pip install -r requirements.txt
+
+    # Serve the docs
+    mkdocs serve
+    ```
+
+---
+
+## Install Python
+
+This project runs on Python & dependent packages.
+
+You'll need to install [Python 3](https://www.python.org/downloads/) & pip (a Python package manager; typically comes with Python installs)
+
+!!! note
+    Specific Python installation instructions will depend on your OS; see above links for more info.
+
+---
+
+## Download the repo locally
+
+From a terminal, enter the command:
+
+```sh
+git clone path/to/repo.git
+```
+
+For example, to download the [After Effects Scripting Guide](https://github.com/docsforadobe/after-effects-scripting-guide/):
+
+```sh
+git clone https://github.com/docsforadobe/after-effects-scripting-guide.git
+```
+
+---
+
+## Install dependencies
+
+Once Python is installed, you'll need to install the required dependencies for the specific documentation guide you're working in.
+
+The dependencies for each repo is held in a text file in the root of the repo, `requirements.txt`.
+
+These are things like the actual system used to build the project ("MkDocs"), as well as any plugins or extensions required for the specific guide you're working in.
+
+**First, open a terminal to the repo's directory.**
+
+Then, you can tell Python to install these dependencies globally onto your device with the following command:
+
+```sh
+pip install -r requirements.txt
+```
+
+If you're wanting to install these locally (for just the local user), you can append the `--user` flag:
+
+```sh
+pip install -r requirements.txt --user
+```
+
+#### MacOS & Virtual Environments
+
+On MacOS, you may need to set up a virtual environment in order for Python to allow you to install these dependencies.
+
+This author isn't familiar enough to explain *why* this is required, though these commands seem to do the trick *before* running the `pip` command above.
+
+```sh
+python3 -m venv venv/
+source venv/bin/activate
+```
+
+This will create a subfolder in the directory, `/venv/`, that will hold these dependencies. These files should not be committed to the repo, with `/venv/` being present in each repo's `.gitignore` file.
+
+---
+
+## Build the project
+
+Once the dependencies are installed, you can run the following command to build a local copy of the docs:
+
+```sh
+mkdocs serve
+```
+
+This will set up a virtual server, render the docs to html, and offer up a local url to view these local docs at.
+
+By default, this local url is `http://127.0.0.1:8000`.
+
+!!! tip
+    Any update to the MkDocs config file (`./mkdocs.yml`) or any of the .md docs files will automagically reload the above pages, showing the updates!
+
+Be sure to keep an eye on the terminal for any potential errors or warnings that may come up while working.

docs/contributing/other-tips.md

@@ -0,0 +1,29 @@
+# Other Tips
+
+Various other tips, suggestions, solutions that we've found to be helpful when working on these guides.
+
+---
+
+## Use code editor extensions!
+
+As markdown is such a common language, there are a *ton* of code editor extensions to help writing it. Take advantage of them!
+
+One specific place this can help is when working with [tables](./style-guide.md#tables). As these can get fairly long and unwieldy, being able to quickly format the table to align columns & fix formatting is *way* better than doing this by hand.
+
+---
+
+## Adding undocumented attributes or methods
+
+If you find attributes or methods that are not mentioned in this documentation, and they are not publically announced by Adobe, please add this warning to attribute/method so the user knows to use it at their own risk.
+
+=== "Rendered"
+
+    !!! warning
+        This method/property is officially undocumented and was found via research. The information here may be inaccurate, and this whole method/property may disappear or stop working some point. Please contribute if you have more information on it!
+
+=== "Markdown"
+
+    ```
+    !!! warning
+        This method/property is officially undocumented and was found via research. The information here may be inaccurate, and this whole method/property may disappear or stop working some point. Please contribute if you have more information on it!
+    ```