Update documentation

Author: alessandro-fazzi

.vscode/extensions.json

@@ -1,8 +1,7 @@
 {
   "recommendations": [
-    "lextudio.restructuredtext",
     "trond-snekvik.simple-rst",
     "streetsidesoftware.code-spell-checker",
-    "streetsidesoftware.code-spell-checker-italian"
+    "swyddfa.esbonio"
   ]
 }

.vscode/settings.json

@@ -1,6 +1,4 @@
 {
-  "restructuredtext.confPath": "${workspaceFolder}/rtfm/source",
-  "restructuredtext.builtDocumentationPath": "${workspaceRoot}/rtfm/build/html",
   "search.exclude": {
     "**/bower_components": true,
     "**/node_modules": true,
@@ -12,24 +10,47 @@
   "restructuredtext.languageServer.trace.server": "messages",
   "restructuredtext.linter.executablePath": "/usr/local/bin/doc8",
   "cSpell.words": [
+    "bloginfo",
+    "browserlistsrc",
+    "browserslistrc",
     "Cest",
     "classmap",
     "Codeception",
     "corejs",
     "endcode",
     "gifsicle",
+    "HAML",
     "helperclass",
     "helperfunc",
+    "htmlentities",
     "javascripts",
     "jpegtran",
+    "jquery",
+    "linenos",
+    "literalinclude",
     "MAILHOG",
     "mobiledetect",
     "mobiledetectlib",
+    "myview",
+    "nvmrc",
     "optipng",
     "phpmailer",
+    "PHUG",
     "Procfile",
     "runcommand",
+    "seealso",
+    "shortcodes",
     "SQLSTATE",
-    "symfony"
-  ]
+    "Stylelint",
+    "stylelintignore",
+    "stylelintrc",
+    "stylesheet",
+    "symfony",
+    "Wordmove",
+    "Worldess",
+    "wpunit"
+  ],
+  "esbonio.sphinx.buildDir": "${workspaceRoot}/rtfm/build",
+  "esbonio.sphinx.confDir": "${workspaceFolder}/rtfm/source",
+  "esbonio.server.pythonPath": "/opt/homebrew/bin/python3"
 }

README.md

@@ -20,7 +20,7 @@ Wordless is a junction between a WordPress plugin and a theme boilerplate that d
 
 ### Complete documentation
 
-Read the complete Wordless documentation at [wordless.readthedocs.io](https://wordless.readthedocs.io/en/latest/?badge=latest) where you'll find - hopefully - all the informations about installation, usage guide, in depth explanation about the stack.
+Read the complete Wordless documentation at [wordless.readthedocs.io](https://wordless.readthedocs.io/en/latest/?badge=latest) where you'll find - hopefully - all the information about installation, usage guide, in depth explanation about the stack.
 
 If you want to contribute to the documentation.
 

rtfm/source/_pages/appendix/acf_gutenberg_blocks.rst

@@ -48,7 +48,7 @@ interface. If absent, then the second will be used.
 You will be obviously free to render the block anywhere in your
 front-end template, since it's a simple partial:
 
-.. code-block:: jade
+.. code-block:: pug
 
     render_partial('blocks/slider')
 

rtfm/source/_pages/appendix/plainphp.rst

@@ -56,6 +56,7 @@ directly including the PHP file.
     we need to use plain PHP functions.
 
 .. _RenderingPhp:
+
 PHP render helpers
 ##################
 

rtfm/source/_pages/appendix/render_static.rst

@@ -23,7 +23,7 @@ This is the definition of ``render_static()`` function:
 
 .. warning::
     Using static rendering could lead to undesired effects by design (not specifically with Wordless).
-    Be sure to know what you're doing. It's not alwas just a matter to be faster.
+    Be sure to know what you're doing. It's not always just a matter to be faster.
 
 Static template example
 #######################
@@ -97,7 +97,7 @@ You have 3 way to handle this:
 * blank ``tmp/`` folder with ``wp wordless theme clear_tmp``
 * from the "Cache management" menu within the admin panel
 
-The "Cache management" menu needs to be activated decommenting this line
+The "Cache management" menu needs to be activated uncommenting this line
 
 .. literalinclude:: /../../wordless/theme_builder/vanilla_theme/config/initializers/backend.php
     :language: php

rtfm/source/_pages/stack/compile.rst

@@ -66,7 +66,7 @@ We love it because it is concise, clear, tidy and clean.
 
 Certainly, becoming fluent in PUG usage could have a not-so-flat
 learning curve,
-but starting from the basics shuold be affordable and the reward is high.
+but starting from the basics should be affordable and the reward is high.
 
 Who compiles PUG?
 """""""""""""""""
@@ -77,7 +77,7 @@ compile (and cache) it. As far as you have the plugin activated you are ok.
 .. important::
 
     By default, you have nothing to do to deploy in production, but if performance is
-    crucial in your project, then you can optimize. See :ref:`PHUGoptimizer` for more informations.
+    crucial in your project, then you can optimize. See :ref:`PHUGoptimizer` for more information.
 
 
 .. _Pug: https://github.com/pugjs/pug
@@ -110,18 +110,18 @@ and are used by the ``entry`` and ``output`` configurations:
 .. literalinclude:: /../../wordless/theme_builder/vanilla_theme/webpack.config.js
     :language: js
     :caption: webpack.config.js
-    :lineno-start: 18
-    :lines: 18-26
+    :lineno-start: 23
+    :lines: 23-38
 
 CSS will be extracted from the bundle by the standard mini-css-extract-plugin_
 
 .. _mini-css-extract-plugin: https://webpack.js.org/plugins/extract-text-webpack-plugin/
 
 .. literalinclude:: /../../wordless/theme_builder/vanilla_theme/webpack.config.js
-    :language: js$
+    :language: js
     :caption: webpack.config.js
-    :lineno-start: 129
-    :lines: 129-131
+    :lineno-start: 99
+    :lines: 99-101
 
 Inclusion of compiled files
 """""""""""""""""""""""""""
@@ -193,36 +193,36 @@ Add another *entry* and producing new bundles is as easy as
 
   .. code-block:: php
 
-        function enqueue_stylesheets() {
-            wp_register_style("main", stylesheet_url("main"), [], false, 'all');
-            wp_register_style("backend", stylesheet_url("backend"), [], false, 'all');
-            wp_enqueue_style("main");
-            wp_enqueue_style("backend");
-        }
-
-        function enqueue_javascripts() {
-            wp_enqueue_script("jquery");
-            wp_register_script("main", javascript_url("main"), [], false, true);
-            wp_register_script("backend", javascript_url("backend"), [], false, true);
-            wp_enqueue_script("main");
-            wp_enqueue_script("backend");
-        }
+    function enqueue_stylesheets() {
+        wp_register_style("main", stylesheet_url("main"), [], false, 'all');
+        wp_register_style("backend", stylesheet_url("backend"), [], false, 'all');
+        wp_enqueue_style("main");
+        wp_enqueue_style("backend");
+    }
+
+    function enqueue_javascripts() {
+        wp_enqueue_script("jquery");
+        wp_register_script("main", javascript_url("main"), [], false, true);
+        wp_register_script("backend", javascript_url("backend"), [], false, true);
+        wp_enqueue_script("main");
+        wp_enqueue_script("backend");
+    }
 
   or add it anywhere in your templates:
 
-  .. code-block:: jade
+  .. code-block:: pug
 
-        header
-            = stylesheet_link_tag('backend')
-        footer
-            = javascript_include_tag('backend')
+    header
+        = stylesheet_link_tag('backend')
+    footer
+        = javascript_include_tag('backend')
 
 Browserslist
 """"""""""""
 
 At theme's root you'll find the `.browserlistsrc`_ file.
 
-By default it's used by Babel and Core-js3 to understand how to polifill
+By default it's used by Babel and Core-js3 to understand how to polyfill
 your ES2015 code. You can understand more about our default configuration
 reading Babel docs at https://babeljs.io/docs/en/babel-preset-env#browserslist-integration
 

rtfm/source/_pages/stack/server.rst

@@ -21,7 +21,7 @@ YARN
 section inside your ``package.json`` file and will execute the matched script.
 
 .. literalinclude:: /../../wordless/theme_builder/vanilla_theme/package.json
-    :lines: 13-20
+    :lines: 13-32
     :language: javascript
     :caption: package.json
 
@@ -44,7 +44,7 @@ As you can see, each line has a simple named command. Each command will be
 launched and *foreman* will:
 
 * run all the listed processes
-* collect all STDOUTs from processes and print theme as one - with fancyness
+* collect all STDOUTs from processes and print theme as one - with fanciness
 * when stopped (CTRL-C) it will stop all of the processes
 
 wp server
@@ -69,7 +69,7 @@ start a web server at address ``127.0.0.1`` on port 3000.
 This is where your browser will automatically go once launched.
 
 .. literalinclude:: /../../wordless/theme_builder/vanilla_theme/webpack.config.js
-    :lines: 94-108
+    :lines: 83-97
     :language: js
     :caption: webpack.config.js
 
@@ -78,10 +78,10 @@ underlying ``wp server``.
 
 Since *BrowserSync* is invoked through a Webpack plugin
 (`browser-sync-webpack-plugin`_) we will benefit from automatic
-**browser autoreloading** when assets are recompiled by Webpack itself.
+**browser auto-reloading** when assets are recompiled by Webpack itself.
 
 The ``files`` option is there because ``.pug`` files are not compiled by
-webpack, so we force watching those files too, thus calling autoreload on
+webpack, so we force watching those files too, thus calling auto-reload on
 template changes too.
 
 .. seealso::
@@ -111,7 +111,7 @@ MailHog
 * View messages in the web UI, or retrieve them with the JSON API
 * Optionally release messages to real SMTP servers for delivery
 
-Wordless is configured to use it by default, so you can test mailouts from
+Wordless is configured to use it by default, so you can test outgoing emails from
 your site, from WordPress and from your forms.
 
 The UI will be at
@@ -134,7 +134,7 @@ This will trigger the ``smtp.php`` initializer:
 Debug in VSCode
 ###############
 
-We ship a ``.vscode/launch.json`` in theme's root which is preconfigured to
+We ship a ``.vscode/launch.json`` in theme's root which is pre-configured to
 launch debugger for XDebug and for JS (both Chrome and FireFox). In order to
 use these configuration you'll need to install some plugins in the editor:
 
@@ -148,6 +148,6 @@ use these configuration you'll need to install some plugins in the editor:
 
 .. note::
     You may need to move ``.vscode/launch.json`` in another location if you
-    are not opening the theme's folder as workspace in VSCode (maybe you prefere to
+    are not opening the theme's folder as workspace in VSCode (maybe you prefer to
     open all the WordPress installation? Don't know...). It's up to you to use it
     as you need it.

rtfm/source/_pages/usage/css_js.rst

@@ -78,13 +78,13 @@ and go on as usual.
 Linters
 """""""
 
-Wordless ships with preconfigured linting of SCSS
+Wordless ships with pre-configured linting of SCSS
 using `Stylelint`_.
 
 It is configured in ``.stylelintrc.json``, you can add exclusion in
 ``.stylelintignore``; all is really standard.
 
-The script ``yarn lint`` is preconfigured to run lint tasks.
+The script ``yarn lint`` is pre-configured to run lint tasks.
 
 .. tip::
 

rtfm/source/_pages/usage/filters.rst

@@ -96,7 +96,7 @@ wordless_tmp_dir_exists
 Sometimes tmp folder in theme directory, may not have write permission in dedicated server, Hence failure to load pug template from tmp.
 In tmp directory, if there is compiled files listed following hook can be used to check file counts and override ensure_tmp_dir function to return true.
 In some cases files can be compiled via command line to generate files in tmp dir.
-here the filter code is added in ``themes/exmaple-theme/config/initializers/hooks.php``
+here the filter code is added in ``themes/example-theme/config/initializers/hooks.php``
 
 wordless_environment
 ##########################
@@ -120,7 +120,7 @@ wordless_environment
 	        return 'production';
         } );
 
-Here the filter code is added in ``themes/exmaple-theme/config/initializers/hooks.php``
+Here the filter code is added in ``themes/example-theme/config/initializers/hooks.php``
 
 If there is different or custom environment name defined this hook can override it, rather than defaulting to development always. For example if environment is called UAT or SIT.
 
@@ -139,10 +139,10 @@ wordless_component_validation_exception
 
 When an object of class ``Wordless\Component`` fails its validation, it will throw an exception
 only if ``ENVIRONMENT`` **is not** ``production``. When in ``production`` nothing will happen, in
-order to be unobstrusive and not breaking the site to your users. The developer will still see
-specific excpetion happening.
+order to be unobtrusive and not breaking the site to your users. The developer will still see
+specific exception happening.
 
-You can customize the behaviour by adding your action as documented in the code.
+You can customize the behavior by adding your action as documented in the code.
 
 What we like to do is to add here a notification to our Sentry account (thanks to
 https://github.com/stayallive/wp-sentry/ plugin)

rtfm/source/_pages/usage/helpers.rst

@@ -21,13 +21,13 @@ all the 40+ tested and documented helpers Wordless gives you for free:
 - ``distance_of_time_in_words()`` - Reports the approximate distance in time
   between two dates
 
-Our favourite convention for writing custom helpers is to write 1 file per
+Our favorite convention for writing custom helpers is to write 1 file per
 function and naming both the same way. It will be easier to find with ```cmd+p``
 😉
 
 **Where is my** ``functions.php`` **?**
 
 In a Wordless theme the isn't a ``functions.php`` file. It was too ugly to us to support it.
 You have simply to consider ``helpers/*.php`` files as the explosion of your old messy
-``functions.php`` into smaller chunks. And since all the helpers you'll write will be autorequired,
+``functions.php`` into smaller chunks. And since all the helpers you'll write will be auto-required,
 defined functions will work exactly the same way you are used to.

rtfm/source/_pages/usage/initializers.rst

@@ -26,7 +26,7 @@ one with a specific target:
   ├──── thumbnail_sizes.php
 
 - **backend**: remove backend components such as widgets, update messages, etc
-- **custom_gutenbers_acf_blocks**: Wordless has built-in support to ACF/Gutenberg blocks. Read more
+- **custom_gutenberg_acf_blocks**: Wordless has built-in support to ACF/Gutenberg blocks. Read more
   at :ref:`Blocks`
 - **custom_post_types**: well... if you need to manage taxonomies, this is the
   place to be