Add content to front page and bring on-line at "future-docs"

.github/workflows/publish.yml

@@ -12,7 +12,9 @@ jobs:
       - uses: actions/checkout@v2
 
       - name: Install Dependencies
-        run: sudo apt-get -y install python3-sphinx furo
+        run: |
+            sudo apt-get -y install python3-sphinx
+            pip3 install furo
 
       - name: Build Site
         run: make html

_templates/page.html

@@ -33,17 +33,17 @@
       <a href="{{ pathto(master_doc) }}"><div class="brand">{{ docstitle if docstitle else project }}</div></a>
     </div>
     <div class="header-right">
-      <div class="theme-toggle-container theme-toggle-header">
+      {#- <div class="theme-toggle-container theme-toggle-header">
         <button class="theme-toggle">
           <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
           <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
           <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
           <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
         </button>
-      </div>
+      </div> -#}
       <label class="toc-overlay-icon toc-header-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
         <div class="visually-hidden">Toggle table of contents sidebar</div>
-        <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+        <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
       </label>
     </div>
   </header>
@@ -74,17 +74,17 @@
           {{ warning("Got an unsupported value for 'top_of_page_button'") }}
           {%- endif -%}
           {#- Theme toggle -#}
-          <div class="theme-toggle-container theme-toggle-content">
+          {#- <div class="theme-toggle-container theme-toggle-content">
             <button class="theme-toggle">
               <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
               <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
               <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
               <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
             </button>
-          </div>
+          </div> -#}
           <label class="toc-overlay-icon toc-content-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
             <div class="visually-hidden">Toggle table of contents sidebar</div>
-            <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+            <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
           </label>
         </div>
         <article role="main">
@@ -127,11 +127,11 @@
             <div class="copyright">
               {%- if hasdoc('copyright') %}
                 {% trans path=pathto('copyright'), copyright=copyright|e -%}
-                  <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+                  <a href="{{ path }}">&#169;</a> {{ copyright }}
                 {%- endtrans %}
               {%- else %}
                 {% trans copyright=copyright|e -%}
-                  Copyright &#169; {{ copyright }}
+                  &#169; {{ copyright }}
                 {%- endtrans %}
               {%- endif %}
             </div>

_templates/partials/icons.html

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <symbol id="svg-menu" viewBox="0 0 10 10">
+    <title>Menu</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10" fill="none" stroke="currentColor"
+      stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
+      <line x1="1" y1="5" x2="9" y2="5"></line>
+      <line x1="1" y1="2.5" x2="9" y2="2.5"></line>
+      <line x1="1" y1="7.5" x2="9" y2="7.5"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-arrow-right" viewBox="0 0 10 10">
+    <title>Expand</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10" fill="none" stroke="currentColor"
+      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
+      <polyline points="3 7.5 5 5 3 2.5"></polyline>
+     </svg>
+  </symbol>
+</svg>

conf.py

@@ -16,6 +16,7 @@
 html_show_sphinx = False
 html_theme_options = {
   'source_repository': 'https://github.com/recoverysource/handbook/',
+  'announcement': '<b>ACTIVE DEVELOPMENT:</b><br />For current documentation, please visit <a href="https://docs.recoverysource.net">docs.recoverysource.net</a>',
 }
 html_title = 'Recovery Source Handbook'
 html_css_files = ['style.css']

essentials/github.rst

@@ -90,12 +90,12 @@ To accept this responsibility ...
 3. Read through the disclaimer and choose the appropriate option.
 
 ..
-  _links
+   _links:
 .. _Fork: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks
 .. _Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with⇲-pull-requests/about-pull-requests
 
 ..
-  _images
+   _images:
 .. |github_homepage| image:: /static/images/updatesite/1_github_homepage.png
 .. |github_create| image:: /static/images/updatesite/2_github_create.png
 .. |github_token| image:: /static/images/updatesite/3_github_token.png

guide/hugo-themes.rst

@@ -3,5 +3,5 @@
 Modify Hugo Themes
 ==================
 
-This should focus on making changes :ref:`Our Template <template-about>`, rather
+This should focus on making changes :ref:`Our Template <template>`, rather
 than creating a new (sub)theme.

guide/principles.rst

@@ -16,7 +16,45 @@ Where our :ref:`Code of Coduct <conduct>` provides a standard of behavior and
 ethical guidelines to help resolve disputes, this page provides guidelines to
 help maintain alignment on mutual goals addressed by this project.
 
+.. _audience:
+
 Target Audience
 ---------------
 
-...
+Our documentation is intended for anyone who wishes to be "the website person"
+for their local 12-step group.
+
+Like any role, this position requires specific skills that may not be possessed
+by everyone. In order to ensure you can successfully fill this role, we have
+provided a basic "job description."
+
+
+As a **website manager**, you will be responsible to:
+
+- **Identify a point of contact who is ultimately responsible for meeting data!**
+
+  + This /may/ be you, but **should** be a registrar.
+
+- Ensure there is a responsible party in charge of web-related expenses.
+- Train other users in your region how to request (or make) changes to content.
+- Monitor and review all changes made to the website(s) you are responsible for.
+- Learn how to first identify an issue and then troubleshoot the root cause.
+- Engage with users who make invalid changes, to provide additional training.
+- Seek training when you find yourself unable to accomplish a task.
+
+Our goal is to provide everything you need (:ref:`training <start>` &
+:ref:`support <support>`) in order to successfully deploy, maintain, and manage
+a website for your group.
+
+.. _docreqs:
+
+Documentation Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This list provides some practical considerations that help define our audience:
+
+- A common standard is "4th-grade reading level," but we should should for 3rd.
+- Readers must be told **how** to copy an example file.
+- Readers are extremely unlikely to look beyond our own documentation.
+- Readers are extremely unlikely to search our documentation when facing issues.
+- Those who follow along may be doing so from a mobile device (mobile-only user).

index.rst

@@ -1,4 +1,104 @@
-.. _index:
+.. _project:
+
+Recovery Source
+===============
+
+**Recovery Source** provides a collection of tools that are meant to demystify
+website maintenance, leaving :ref:`anyone <def-anyone>` with the skills required
+to support :ref:`12-Step <def-12step>` groups.
+
+:ref:`Our goal <principles>` is to help 12-Step groups reach out to those who
+are still suffering.
+
+.. _services:
+
+**What We Provide:**
+
+:ref:`Recovery Source Handbook <project>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- :ref:`Get Started <start>`
+
+*This* handbook is designed to take our :ref:`target audience <audience>` from
+absolute beginner to a competent website administrator who is able to support a
+website for their 12-Step group.
+
+The documentation provided here covers the breadth of our projects and provides
+the foundational knowledge required to understand how websites work and how all
+of the pieces fit together.
+
+:ref:`Sober Page <domain>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The primary purpose of ``Sober Page`` is to offer a free :ref:`domain name
+<def-domain>` to 12-Step ``Sober Support Groups``, allowing them to easily
+create a website and place it onto the internet using a standardized URL format
+(ex. https\://**aa0**-**1**.sober.page for Area **0**, District **1** of **A.A.**).
+
+This :ref:`domain solution <domain>` allows us to easily absorb the overhead
+required to provide a :ref:`basic set of services <soberpage>`, which grants us
+a tremendous amount of flexibility to resolve a wide variety of "common" issues.
+
+With https://sober.page/, groups can avoid the cost and hassle of purchasing and
+naming their own domain, or they can mix-and-match whatever works best in their
+current situation.
+
+:ref:`Website Template <template>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `Live Demo <https://template-demo.recoverysource.net>`__
+
+Our website template provides a "turn-key" website solution that enables you to
+focus on little more than meeting accuracy. This removes many stumbling blocks
+commonly seen on new websites, and allows us to ensure the accuracy of this
+handbook.
+
+Unlike website builders (wix, shopify, squarespace, etc.) or content management
+systems (wordpress, drupal, etc.), our solution is based on a :ref:`Static Site
+Generator (SSG) <def-ssg>`, which means the website can be hosted anywhere and
+you can easily keep your own working copy as a functional backup of the live.
+
+If any of this explanation sounds confusing but you still want what we have,
+then please :ref:`Get Started <start>` with our handbook and :ref:`Ask Us
+<support>` if something is not properly explained.
+
+:ref:`AAMod Plugin <aamod>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `Our Features <https://aamod-demo.recoverysource.net>`__
+- `Mainroad Features <https://mainroad-demo.netlify.app>`__
+
+The real heavy lifter behind our template is ``AAMod``, which improves
+accessibility and adds website features built to serve the needs of 12-Step
+groups.
+
+Many of these features are written in a way that should enable them to be easily
+re-used in other projects with very few modifications.
+
+.. note::
+   - Hugo is a :ref:`Static Site Generator (SSG) <def-ssg>`.
+   - Mainroad is a clean and lightweight "theme" for Hugo.
+   - AAMod is designed as a "sub-theme" of Mainroad.
+   - AAMod functions as both a Hugo theme, and as a set of helper scripts.
+
+.. _support:
+
+Support
+-------
+
+If you struggle to follow this handbook, we encourage you to first take a break,
+go for a walk, and then return to :ref:`Getting Started <start>`. Our goal is
+to teach you everything, so if there's something we missed, please let us know
+using this `Discord Link`_.
+
+Not all things can be answered in documentation, especially if you would like us
+to help with maintenance tasks; our `Discord Link`_ is open to all who wish to
+support 12-Step sober support group websites.
+
+.. _Discord Link: https://discord.gg/hjTJSA7Ynu>
+
+..
+   _menu:
 
 .. toctree::
    :hidden:
@@ -83,22 +183,3 @@
    guide/html
    guide/css
    guide/actions
-
-
-Recovery Source
-===============
-
-- We provide a set of projects (and other documentation) to help 12-step groups who are struggling with technology-based outreach.
-- Recovery Source is a team that is driven by the 12th step; we do not accept donations from those whom we serve.
-- What is a 12-step group (and AA)? (where/why it started)
-- Complete description of each project
-
-
-``Recovery Source`` is a collective effort to provide simple and efficient
-solutions in the spirit of open source that aid 12-Step Programs.
-
-Projects:
-
-  - :ref:`Hugo AAMod <aamod-about>` [`demo <https://aamod-demo.recoverysource.net/>`__]
-  - :ref:`Website Template <aamod-newsite>` [`demo <https://template-demo.recoverysource.net>`__]
-  - :ref:`Sober Page <soberpage>` [`live <https://sober.page>`__]

module/about.rst

@@ -1,4 +1,4 @@
-.. _aamod-about:
+.. _aamod:
 
 About Hugo
 ==========
@@ -18,14 +18,14 @@ static websites are immune to the vast majority of new vulnerabilities, meaning
 your website will only ever have to change/update for content or design.
 
 This added documentation walks a user through deploying this website and hosting
-it using `Github Pages`_. If you have decided you want what we (`Area 63`_) have
+it using `Github Pages`_. If you have decided you want what we  have
 and want to avoid major hurdles to get there, then you are ready to take
 :ref:`certain steps<aamod-newsite>`.
 
 Website Bootstrap
 -----------------
 
-The `Hugo Template`_ repository holds a copy of ``exampleSite/`` (from `AAMod`_)
+The `Hugo Template`_ repository holds a copy of ``exampleSite/``
 with customization done to help bootstrap a brand :ref:`aamod-newsite`
 This lets you skip a lot of requisite knowledge and get straight maintenance.
 
@@ -49,7 +49,6 @@ into content suitable for hugo to turn into a website.
 
 .. _Hugo: https://gohugo.io/
 .. _Hugo Template: https://github.com/recoverysource/hugo-template
-.. _AAMod: https://github.com/recoverysource/aamod
 .. _Github Pages: https://pages.github.com/
 .. _Area 63: https://area63aa.org/
 .. _Mainroad: https://themes.gohugo.io/themes/mainroad/

project/getting-started.rst

@@ -1,4 +1,4 @@
-.. _getting-started:
+.. _start:
 
 Getting Started
 ===============

project/glossary.rst

@@ -1,12 +1,28 @@
 .. _glossary:
 
-Glossary
-========
+Vocabulary
+==========
 
 This glossary introduces common terminology used within this project. If you are
 new to our project documentation, we recommend briefly skimming through this
 page in order to familiarize yourself with common terms.
 
+.. _def-12step:
+
+12-Step Group
+-------------
+
+TODO
+
+.. _def-anyone:
+
+Anyone
+------
+
+This documentation uses "anyone" to refer to any person of any age or background
+who may wish to follow this documentation. This term is described in greater
+detail as our ":ref:`target audience <audience>`".
+
 .. _def-commit:
 
 Commit