Merge branch 'main' into plugin-ci

.all-contributorsrc

@@ -13,12 +13,32 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "shinde-rahul",
+      "name": "Rahul Shinde",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1046788?v=4",
+      "profile": "https://github.com/shinde-rahul",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "dennisameling",
+      "name": "Dennis Ameling",
+      "avatar_url": "https://avatars.githubusercontent.com/u/17739158?v=4",
+      "profile": "https://dennisameling.com",
+      "contributions": [
+        "doc",
+        "review"
+      ]
     }
   ],
   "contributorsPerLine": 7,
   "projectName": "developer-documentation-new",
   "projectOwner": "mautic",
   "repoType": "github",
   "repoHost": "https://github.com",
-  "skipCi": true
+  "skipCi": true,
+  "commitConvention": "angular"
 }

.github/styles/Mautic/FeatureList.yml

@@ -54,6 +54,8 @@ swap:
   segments: Segments
   stage: Stage
   stages: Stages
+  sync engine: Sync Engine
+  sync report: Sync Report
   theme: Theme
   themes: Themes
   user: User

.github/styles/Vocab/Mautic/accept.txt

@@ -6,6 +6,10 @@ Autoloader
 autoloader
 Autowired
 autowired
+Autowiring
+autowiring
+autowire
+autowires
 bcc
 Beanstalkd
 Bing
@@ -106,6 +110,7 @@ SugarCRM
 Suhosin
 Symfony
 Todo
+tooltip
 Transifex
 TRUE
 true
@@ -123,4 +128,10 @@ www
 YAML
 Zapier
 Zoho
-Tooltip
+middleware
+URIs
+false
+timeframe
+OAuth1a
+OAuth2
+Tooltip

.gitignore

@@ -1,3 +1,6 @@
 build
 .idea
-__pycache__
+__pycache__
+.DS_Store
+docs/code_samples_downloaded/*
+!docs/code_samples_downloaded/.gitkeep

README.md

@@ -1,6 +1,6 @@
 [![Documentation Status][RTD badge URL]][RTD URL]
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/developer-documentation-new)
@@ -20,6 +20,21 @@ For more background, our end goal, and to let us know if you want to help, pleas
 
 [![Link to YouTube video with explanation of the current developer documentation structure][YouTube video image]][YouTube video URL]
 
+## Adding a code sample
+
+Code samples get downloaded from GitHub to ensure that they're always up to date. If you want to add a new code sample, follow these two steps:
+
+1. Create a file in `docs/code_samples/` and add a permalink in there. Look at other files in that directory for examples. URLs should always start with `https://raw.githubusercontent.com/...` to ensure that Sphinx can download the file correctly.
+2. In any documentation file, add a `literalinclude` block to include the code, like so:
+
+```
+.. The link to this file is defined in docs/code_samples/helloworld_entity_world.py 
+.. literalinclude:: ../code_samples_downloaded/Entity_World.php
+    :language: php
+```
+
+Tip: downloaded files get cached in `docs/code_samples_downloaded` to prevent overloading GitHub with download requests. If you change the URL to a file, simply remove the cached file from `docs/code_samples_downloaded` and Sphinx automatically re-downloads it.
+
 ## Build documentation locally
 
 - [RST Syntax Cheatsheet][RST Cheatsheet]
@@ -34,7 +49,14 @@ The following provides instructions for how to build docs locally for visualizat
 4. CD into the docs directory `cd [path to this repo]/docs`
 5. Run `make html`
 6. This will generate HTML in docs/build/html. Setup a web server with the web root as docs/build/html or open docs/build/html/index.html in a browser.
-
+
+## Troubleshooting
+
+If the build isn't working for some reason, here's some tips:
+
+- Try running the `make html` command in the terminal: `cd docs && make html`. This command normally provides a lot of additional context.
+- If the preview isn't working, click the `esbonio` section in the bottom right corner of the VS Code window. That rebuilds the docs and previews, and tells you if something is wrong.
+
 ### Vale
 Before pushing, run Vale and address suggestions and errors as applicable.
 1. Install [`vale`][Vale] 
@@ -47,6 +69,33 @@ You can automatically build changes to rst files using a file watcher.
 
 <img width="753" alt="Screen Shot 2021-10-06 at 15 52 06" src="https://user-images.githubusercontent.com/63312/136281761-204861f9-340a-4e3e-8ce5-e0584236303c.png">
 
+### Style guide
+
+Please consult Mautic's [`style-guide`][Style guide] before contributing to the documentation. Some rules get enforced through Vale.
+
+As a quick reference, here's the list of headings Mautic uses:
+
+```
+H1: ############
+H2: ****************
+H3: ============
+H4: ----------------
+H5: ~~~~~~~~~~~~
+```
+
+ <!-- vale off -->
+
+### Converting markdown to reStructuredText
+
+ <!-- vale on -->
+
+Mautic's documentation uses ``reStructuredText``, or ``.rst`` files. Luckily, there's converters available that help you convert ``.md`` to ``.rst`` files. Here's an example of ``m2r`` - this converter also converts tables into ``list-table`` directives properly.
+
+```
+pip install m2r
+# This creates a new file with the .rst extension:
+m2r my_markdown_file.md
+```
 
 [ReadTheDocs]: <https://readthedocs.org>
 [Legacy dev docs]: <https://github.com/mautic/developer-documentation>
@@ -60,6 +109,7 @@ You can automatically build changes to rst files using a file watcher.
 [Sphinx Template]: <https://github.com/readthedocs/sphinx_rtd_theme/tree/master/docs/demo>
 [Sphinx Demo]: <https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/structure.html>
 [Vale]: <https://docs.errata.ai/vale/install>
+[Style Guide]: <https://contribute.mautic.org/education-team/technical-writing-styleguide>
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -68,9 +118,13 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->
 <table>
-  <tr>
-    <td align="center"><a href="https://robert-parker.me"><img src="https://avatars.githubusercontent.com/u/25473863?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Robert Parker</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=diaboloshogunate" title="Documentation">📖</a></td>
-  </tr>
+  <tbody>
+    <tr>
+      <td align="center"><a href="https://robert-parker.me"><img src="https://avatars.githubusercontent.com/u/25473863?v=4?s=100" width="100px;" alt="Robert Parker"/><br /><sub><b>Robert Parker</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=diaboloshogunate" title="Documentation">📖</a></td>
+      <td align="center"><a href="https://github.com/shinde-rahul"><img src="https://avatars.githubusercontent.com/u/1046788?v=4?s=100" width="100px;" alt="Rahul Shinde"/><br /><sub><b>Rahul Shinde</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=shinde-rahul" title="Documentation">📖</a></td>
+      <td align="center"><a href="https://dennisameling.com"><img src="https://avatars.githubusercontent.com/u/17739158?v=4?s=100" width="100px;" alt="Dennis Ameling"/><br /><sub><b>Dennis Ameling</b></sub></a><br /><a href="https://github.com/mautic/developer-documentation-new/commits?author=dennisameling" title="Documentation">📖</a> <a href="https://github.com/mautic/developer-documentation-new/pulls?q=is%3Apr+reviewed-by%3Adennisameling" title="Reviewed Pull Requests">👀</a></td>
+    </tr>
+  </tbody>
 </table>
 
 <!-- markdownlint-restore -->

docs/Makefile

@@ -9,6 +9,7 @@ SOURCEDIR     =
 BUILDDIR      = build
 LINKSDIR      = links
 LINKCHECKDIR  = build/linkcheck
+CODESAMPLESDIR = code_samples
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -33,7 +34,23 @@ link:
 link_text = \"$$link_text\" \n\
 link_url = \"$$link_url\" \n\n\
 link.xref_links.update({link_name: (link_text, link_url)})" \
-  > $(LINKSDIR)/$$file_name".py" \
+  > $(LINKSDIR)/$$file_name".py"
+
+.PHONY: code-sample
+code-sample:
+	@read -p "Enter a Unique File Name (with .php suffix): " file_name; \
+	read -p "Enter the URL to the file (should start with https://raw.githubusercontent.com/...): " file_url; \
+	read -p "Enter the .py file name (use_lower_case_and_underscore of file name): " py_file_name; \
+	echo "The file name is: " $$file_name; \
+	echo "The URL is: " $$file_url; \
+	echo "The .py file name is: " $$py_file_name; \
+	echo "Creating the file: " $(CODESAMPLESDIR)/$$py_file_name".py"; \
+	echo "Enter the link in content as .. literalinclude:: ../code_samples_downloaded/"$$file_name; \
+	echo "Make sure you build and test the code sample."; \
+  echo "from . import _main_code_sample\n\noutput_file_name = \"$$file_name\" \n\
+url = \"$$file_url\" \n\n\
+_main_code_sample.code_samples.update({output_file_name: (url)})" \
+  > $(CODESAMPLESDIR)/$$py_file_name".py"
 
 .PHONY: checklinks
 checklinks:

docs/_static/tablefix.css

@@ -0,0 +1,14 @@
+/* override table width restrictions */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.wy-table-responsive {
+    margin-bottom: 24px;
+    max-width: 100%;
+    overflow: visible;
+}
+
+.wy-table-responsive th p {
+    margin-bottom: unset;
+}

docs/_static/theme.css

@@ -0,0 +1,15 @@
+.wy-side-nav-search, .wy-nav-side {
+    background-color: #4e5e9e;
+}
+
+.wy-menu-vertical p.caption {
+    color: #fdb933;
+}
+
+a {
+    color: #4e5e9e;
+}
+
+.wy-menu-vertical a, .wy-side-nav-search>a {
+    color: #ffffff;
+}

docs/_templates/layout.html

@@ -0,0 +1,2 @@
+{% extends "!layout.html" %}
+{% set css_files = css_files + ["_static/tablefix.css"] + ["_static/theme.css"] %}

docs/code_samples/__init__.py

@@ -0,0 +1,7 @@
+from os.path import dirname, basename, isfile
+
+import glob
+# Walk through all files in this folder
+modules = glob.glob(dirname(__file__)+"/*.py")
+
+__all__ = [ basename(f)[:-3] for f in modules if isfile(f)]

docs/code_samples/_main_code_sample.py

@@ -0,0 +1,2 @@
+# We need this Python dictionary so that other files in this folder can extend it.
+code_samples = {}

docs/code_samples/helloworld_entity_world.py

@@ -0,0 +1,8 @@
+from . import _main_code_sample
+
+# Output file name must be unique!
+output_file_name = "Entity_World.php"
+# Ensure that the URL always starts with https://raw.githubusercontent.com/...
+url = "https://raw.githubusercontent.com/mautic/plugin-helloworld/mautic-4/Entity/World.php" 
+
+_main_code_sample.code_samples.update({output_file_name: (url)})