Merge pull request #1752 from INN/809-releases-checklist

Save the Largo Release Checklist in Largo's developer docs

docs/SUPPORT.rst

@@ -0,0 +1,12 @@
+Support
+=======
+
+.. this file was added for https://github.com/INN/largo/issues/1713
+   we're trying a ``docs/SUPPORT.rst` file to see if it triggers GitHub's automated support file detection
+
+Largo has many forms of documentation.
+
+- User documentation is available at `largo.inn.org <https://largo.inn.org>`_ and `support.inn.org <https://support.inn.org>`_
+- Developer documentation is available at `largo.readthedocs.io <https://largo.readthedocs.io>`_.
+- We're also available via email at `[email protected] <mailto:[email protected]>`_.
+

docs/api/index.rst

@@ -1,55 +1,7 @@
 Function reference by file
 ==========================
 
-* `functions.php <functions.html>`_
-* `feed-mailchimp.php <feed-mailchimp.html>`_
-* `archive.php <archive.html>`_
-* `options.php <options.html>`_
-* `inc/conditionals.php <inc/conditionals.html>`_
-* `inc/widgets.php <inc/widgets.html>`_
-* `inc/header-footer.php <inc/header-footer.html>`_
-* `inc/update.php <inc/update.html>`_
-* `inc/post-templates.php <inc/post-templates.html>`_
-* `inc/dashboard.php <inc/dashboard.html>`_
-* `inc/open-graph.php <inc/open-graph.html>`_
-* `inc/sidebars.php <inc/sidebars.html>`_
-* `inc/custom-feeds.php <inc/custom-feeds.html>`_
-* `inc/featured-content.php <inc/featured-content.html>`_
-* `inc/post-tags.php <inc/post-tags.html>`_
-* `inc/nav-menus.php <inc/nav-menus.html>`_
-* `inc/enqueue.php <inc/enqueue.html>`_
-* `inc/term-meta.php <inc/term-meta.html>`_
-* `inc/editor.php <inc/editor.html>`_
-* `inc/metabox-api.php <inc/metabox-api.html>`_
-* `inc/users.php <inc/users.html>`_
-* `inc/related-content.php <inc/related-content.html>`_
-* `inc/term-sidebars.php <inc/term-sidebars.html>`_
-* `inc/post-social.php <inc/post-social.html>`_
-* `inc/avatars.php <inc/avatars.html>`_
-* `inc/post-metaboxes.php <inc/post-metaboxes.html>`_
-* `inc/term-icons.php <inc/term-icons.html>`_
-* `inc/ajax-functions.php <inc/ajax-functions.html>`_
-* `inc/helpers.php <inc/helpers.html>`_
-* `inc/verify.php <inc/verify.html>`_
-* `inc/custom-less-variables.php <inc/custom-less-variables.html>`_
-* `inc/featured-media.php <inc/featured-media.html>`_
-* `inc/images.php <inc/images.html>`_
-* `inc/byline_class.php <inc/byline_class.html>`_
-* `inc/deprecated.php <inc/deprecated.html>`_
-* `inc/taxonomies.php <inc/taxonomies.html>`_
-* `inc/customizer/customizer.php <inc/customizer/customizer.html>`_
-* `inc/wp-taxonomy-landing/functions/cftl-series-order.php <inc/wp-taxonomy-landing/functions/cftl-series-order.html>`_
-* `inc/wp-taxonomy-landing/functions/cftl-admin.php <inc/wp-taxonomy-landing/functions/cftl-admin.html>`_
-* `inc/avatars/functions.php <inc/avatars/functions.html>`_
-* `inc/widgets/largo-image-widget.php <inc/widgets/largo-image-widget.html>`_
-* `inc/widgets/largo-twitter.php <inc/widgets/largo-twitter.html>`_
-* `inc/widgets/largo-facebook.php <inc/widgets/largo-facebook.html>`_
-* `inc/widgets/largo-about.php <inc/widgets/largo-about.html>`_
-* `inc/widgets/largo-recent-comments.php <inc/widgets/largo-recent-comments.html>`_
-* `inc/widgets/largo-recent-posts.php <inc/widgets/largo-recent-posts.html>`_
-* `inc/widgets/largo-post-series-links.php <inc/widgets/largo-post-series-links.html>`_
-* `inc/widgets/largo-taxonomy-list.php <inc/widgets/largo-taxonomy-list.html>`_
-* `inc/widgets/largo-author-bio.php <inc/widgets/largo-author-bio.html>`_
-* `homepages/homepage.php <homepages/homepage.html>`_
-* `homepages/zones/zones.php <homepages/zones/zones.html>`_
-* `homepages/layouts/HomepageSingleWithSeriesStories.php <homepages/layouts/HomepageSingleWithSeriesStories.html>`_
+.. toctree::
+   :glob:
+
+   **

docs/developers/child-themes/advanced-development.rst

@@ -0,0 +1,14 @@
+Advanced Theme Development and Modification
+-------------------------------------------
+
+We've created a `Largo-Sample-Child-Theme repository <https://github.com/INN/Largo-Sample-Child-Theme>`_ to illustrate how we organize child themes that extend Largo.
+
+Visit the repository page to learn more about the following as they pertain to Largo-based child themes:
+
+- `Unit Tests and Continuous Integration <https://github.com/INN/Largo-Sample-Child-Theme/blob/master/tests/readme.md>`_
+- `Stylesheets (LESS and CSS) <https://github.com/INN/Largo-Sample-Child-Theme/blob/master/less/readme.md>`_
+- `Theme Directory Layout <https://github.com/INN/Largo-Sample-Child-Theme#theme-directory-structure>`_
+- `Custom Theme Javascript or CSS <https://github.com/INN/Largo-Sample-Child-Theme#removing-or-replacing-largo-javascript-or-css>`_
+- `Removing or replacing Largo Javascript or CSS <https://github.com/INN/Largo-Sample-Child-Theme#removing-or-replacing-largo-javascript-or-css>`_
+
+You can also look at other themes we've made. These themes are nested in what we call Umbrella Repositories, which contain themes and related files in a framework allowing for deployment. A list of these Umbrella Repositories can be found `by searching for 'umbrella-' on INN's GitHub page <https://github.com/INN?utf8=%E2%9C%93&q=umbrella-&type=&language=>`_. If you'd like to set up you own umbrella repo, see `our umbrella boilerplate <https://github.com/INN/umbrella-boilerplate>`_.

docs/developers/child-themes/basic-style-changes.rst

@@ -0,0 +1,16 @@
+Changing Basic Styling
+----------------------
+
+Largo has a built-in way to change some basic styling options.
+
+To enable this option, from the *Appearance* > *Theme Options* screen click on the "Advanced" tab and check the box labelled "Enable Custom LESS to CSS For Theme Customization" and then save the settings.
+
+.. image:: http://assets.apps.inn.org/largo-docs/enable-less-css.png
+
+You will now see an additional menu item under the Appearance menu labelled "CSS Variables". From this menu you will be able to change some basic styling attributes of your Largo site, including the color scheme, fonts and font-sizes.
+
+.. image:: http://assets.apps.inn.org/largo-docs/less-css-menu.png
+
+This option is only intended for making some basic changes to your site's styles. For anything more complex you will need to create a child theme.
+
+

docs/developers/childthemes.rst → docs/developers/child-themes/creating.rst

@@ -1,8 +1,3 @@
-Using Child Themes
-==================
-
-Child themes are `a feature of WordPress <https://largo.readthedocs.io/en/write-the-docs/developers/childthemes.html>`_ that allow you to extend and override the parent theme that the child theme is based upon. We encourage you to create a child theme for your project.
-
 Creating Child Themes
 ---------------------
 
@@ -35,30 +30,3 @@ To use this child theme, `simply download and unzip it <https://github.com/INN/L
 Now that you have a child theme created, login to your WordPress site and go to Appearance > Themes. Find your child theme, click "activate" and then you should see your new child theme in action on your site and can begin customizing.
 
 
-Changing Basic Styling
-----------------------
-
-Largo has a built-in way to change some basic styling options.
-
-To enable this option, from the *Appearance* > *Theme Options* screen click on the "Advanced" tab and check the box labelled "Enable Custom LESS to CSS For Theme Customization" and then save the settings.
-
-.. image:: http://assets.apps.inn.org/largo-docs/enable-less-css.png
-
-You will now see an additional menu item under the Appearance menu labelled "CSS Variables". From this menu you will be able to change some basic styling attributes of your Largo site, including the color scheme, fonts and font-sizes.
-
-.. image:: http://assets.apps.inn.org/largo-docs/less-css-menu.png
-
-This option is only intended for making some basic changes to your site's styles. For anything more complex you will need to create a child theme.
-
-Advanced Theme Development and Modification
--------------------------------------------
-
-We've created a `Largo-Sample-Child-Theme repository <https://github.com/INN/Largo-Sample-Child-Theme>`_ to illustrate how we organize child themes that extend Largo.
-
-Visit the repository page to learn more about the following as they pertain to Largo-based child themes:
-
-- `Unit Tests and Continuous Integration <https://github.com/INN/Largo-Sample-Child-Theme/blob/master/tests/readme.md>`_
-- `Stylesheets (LESS and CSS) <https://github.com/INN/Largo-Sample-Child-Theme/blob/master/less/readme.md>`_
-- `Theme Directory Layout <https://github.com/INN/Largo-Sample-Child-Theme#theme-directory-structure>`_
-- `Custom Theme Javascript or CSS <https://github.com/INN/Largo-Sample-Child-Theme#removing-or-replacing-largo-javascript-or-css>`_
-- `Removing or replacing Largo Javascript or CSS <https://github.com/INN/Largo-Sample-Child-Theme#removing-or-replacing-largo-javascript-or-css>`_

docs/developers/index.rst

@@ -10,6 +10,32 @@ If you use Largo for a project we'd love to hear from you so can we add you to o
 
 The preferred way of building a site with Largo is by creating a WordPress child theme. We have created a `sample, heavily documented, child theme <childthemes.html#advanced-theme-development-and-modification>`_ to help you understand the way we structure our child themes in the hopes that it will give you a solid framework to get started. There is more information on setting up Largo and `using child themes <../users/download.html#creating-child-themes>`_ in the download and installation section of our documentation.
 
+Bug Reports and Feature Requests
+--------------------------------
+
+Our preferred way for you to submit bug reports, requests for new features or even questions about how things work in Largo is by `opening a new issue on the Largo github repository <https://github.com/INN/Largo/issues>`_.
+
+Contributing to Largo
+---------------------
+
+We welcome (and encourage) anyone who wants to contribute back to the project.
+
+To begin, `please review our contribution guidelines <https://github.com/INN/docs/blob/master/how-to-work-with-us/contributing.md>`_.
+
+We have many ways you can contribute and not all are technical. Wherever possible we will flag issues that we believe are `good for beginners <https://github.com/INN/Largo/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+for+beginners%22>`_ or for less/non-technical contributors (`writing/improving documentation <https://github.com/INN/Largo/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+needs+docs%22>`_, etc.).
+
+Our roadmap, open issues, suggested features and discussion can always be found in the issues section of the `Largo github repository <https://github.com/INN/Largo/issues>`_.
+
+We also have documentation on the `Anatomy of a Pull Request and Submission Protocol <https://github.com/INN/docs/blob/master/how-to-work-with-us/pull-requests.md>`_ and `Contributing to the INN Nerds docs repo using Github.com <https://github.com/INN/docs/blob/master/how-to-work-with-us/via-github.md>`_ which explain, at a high level, the process of contributing to Github projects, generally.
+
+If you would like to help with the documentation, here are some resources:
+
+- `Sphinx' PHP domain-specific markup <http://mark-story.com/posts/view/sphinx-phpdomain-released>`_
+- `Sphinx reStructuredText primer and quickstart guide <http://sphinx-doc.org/rest.html>`_
+
+
+If you have feedback on this collection of documentation, please `get in touch <../feedback.html>`_.
+
 Setting up a development environment
 ------------------------------------
 
@@ -29,23 +55,19 @@ We encourage all INN member organizations looking to add features to or otherwis
 Child Themes
 ------------
 
-What *is* a child theme?
-````````````````````````
+A child theme is a theme that inherits the functionality and styling of another theme, called the parent theme. Child themes are the recommended way of modifying an existing theme. Child themes are `a feature of WordPress <https://developer.wordpress.org/themes/advanced-topics/child-themes/>`_ that allow you to extend and override the parent theme that the child theme is based upon. We encourage you to create a child theme for your website.
 
-From the `WordPress Codex <https://codex.wordpress.org/Child_Themes>`_:
+You should use a child theme in order to make it easier to upgrade to future versions of the Largo parent theme. Child themes allow you to put your modifications to Largo in a place that won't be wiped out when you update Largo. WordPress has a `tutorial you can follow <https://developer.wordpress.org/themes/advanced-topics/child-themes/>`_ that explains how to create and configure a child theme.
 
-  A child theme is a theme that inherits the functionality and styling of another theme, called the parent theme. Child themes are the recommended way of modifying an existing theme.
-
-Why should you use a child theme?
-`````````````````````````````````
-In order to make it easier to upgrade to future versions of the Largo parent theme, you will want to add any customizations that are unique to your site by creating a child theme. WordPress has a `tutorial you can follow <http://codex.wordpress.org/Child_Themes>`_ that explains how to create and configure a child theme.
-
-**More:** `Using Child Themes <../developers/childthemes.html>`_.
 
 .. toctree::
-    :maxdepth: 2
+   :glob:
 
-    childthemes
+   child-themes/creating
+   child-themes/basic-style-changes
+   child-themes/advanced-development
+   upgrade-largo
+   child-themes/*
 
 Custom Post Templates
 ---------------------
@@ -66,6 +88,7 @@ A few brief technical notes that might be helpful as you get started:
     :maxdepth: 2
 
     technicalnotes
+    release-checklist
     grunt-commands
     hooksfilters
     plugin-compat
@@ -80,32 +103,6 @@ It may be helpful to  `read Largo's source on Github <https://github.com/INN/Lar
 .. toctree::
     :maxdepth: 2
 
-    /api/index
     constants
     hooksfilters
-
-Bug Reports and Feature Requests
---------------------------------
-
-Our preferred way for you to submit bug reports, requests for new features or even questions about how things work in Largo is by `opening a new issue on the Largo github repository <https://github.com/INN/Largo/issues>`_.
-
-Contributing to Largo
----------------------
-
-We welcome (and encourage) anyone who wants to contribute back to the project.
-
-To begin, `please review our contribution guidelines <https://github.com/INN/docs/blob/master/how-to-work-with-us/contributing.md>`_.
-
-We have many ways you can contribute and not all are technical. Wherever possible we will flag issues that we believe are `good for beginners <https://github.com/INN/Largo/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+for+beginners%22>`_ or for less/non-technical contributors (`writing/improving documentation <https://github.com/INN/Largo/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+needs+docs%22>`_, etc.).
-
-Our roadmap, open issues, suggested features and discussion can always be found in the issues section of the `Largo github repository <https://github.com/INN/Largo/issues>`_.
-
-We also have documentation on the `Anatomy of a Pull Request and Submission Protocol <https://github.com/INN/docs/blob/master/how-to-work-with-us/pull-requests.md>`_ and `Contributing to the INN Nerds docs repo using Github.com <https://github.com/INN/docs/blob/master/how-to-work-with-us/via-github.md>`_ which explain, at a high level, the process of contributing to Github projects, generally.
-
-If you would like to help with the documentation, here are some resources:
-
-- `Sphinx' PHP domain-specific markup <http://mark-story.com/posts/view/sphinx-phpdomain-released>`_
-- `Sphinx reStructuredText primer and quickstart guide <http://sphinx-doc.org/rest.html>`_
-
-
-If you have feedback on this collection of documentation, please `get in touch <../feedback.html>`_.
+    /api/index