Merge pull request #38 from rootski-io/knowledge-base-home-page

Knowledge base home page
rootski-io · Mar 7, 2022 · a60579f · a60579f
2 parents 03bc0da + 9e65e81
commit a60579f
Show file tree

Hide file tree

Showing 14 changed files with 345 additions and 417 deletions.
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -1,6 +1,7 @@
 {
   "files": [
-    "CONTRIBUTORS.md"
+    "CONTRIBUTORS.md",
+    "README.md"
   ],
   "imageSize": 100,
   "commit": false,
@@ -29,6 +30,8 @@
       "avatar_url": "https://avatars.githubusercontent.com/u/32227767?v=4",
       "profile": "https://github.com/phitoduck",
       "contributions": [
+        "mentoring",
+        "code"
       ]
     }
   ],
@@ -37,5 +40,6 @@
   "projectOwner": "rootski-io",
   "repoType": "github",
   "repoHost": "https://github.com",
-  "skipCi": true
+  "skipCi": true,
+  "commitConvention": "none"
 }
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,10 @@
 rootski_api/postgres
 
+# all-contributors CLI
+package-lock.json
+package.json
+node_modules/
+
 # CDK
 **/*cdk.out
 

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -1 +1,15 @@
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tr>
+    <td align="center"><a href="https://github.com/ir3456"><img src="https://avatars.githubusercontent.com/u/25242220?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Isaac Robbins</b></sub></a><br /><a href="https://github.com/rootski-io/rootski/commits?author=ir3456" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/jabracadabrah"><img src="https://avatars.githubusercontent.com/u/59886656?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Josh Abrahamsen</b></sub></a><br /><a href="#infra-jabracadabrah" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
+    <td align="center"><a href="https://github.com/phitoduck"><img src="https://avatars.githubusercontent.com/u/32227767?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Eric Riddoch</b></sub></a><br /><a href="#mentoring-phitoduck" title="Mentoring">🧑‍🏫</a> <a href="https://github.com/rootski-io/rootski/commits?author=phitoduck" title="Code">💻</a></td>
+  </tr>
+</table>
 
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ rootski is developed by volunteers! Emojis represent types of contributions, ([e
   <tr>
     <td align="center"><a href="https://github.com/ir3456"><img src="https://avatars.githubusercontent.com/u/25242220?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Isaac Robbins</b></sub></a><br /><a href="https://github.com/rootski-io/rootski/commits?author=ir3456" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/jabracadabrah"><img src="https://avatars.githubusercontent.com/u/59886656?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Josh Abrahamsen</b></sub></a><br /><a href="#infra-jabracadabrah" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
-    <td align="center"><a href="https://github.com/phitoduck"><img src="https://avatars.githubusercontent.com/u/32227767?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Eric Riddoch</b></sub></a><br /><a href="#mentoring-phitoduck" title="Mentoring">🧑‍🏫</a></td>
+    <td align="center"><a href="https://github.com/phitoduck"><img src="https://avatars.githubusercontent.com/u/32227767?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Eric Riddoch</b></sub></a><br /><a href="#mentoring-phitoduck" title="Mentoring">🧑‍🏫</a> <a href="https://github.com/rootski-io/rootski/commits?author=phitoduck" title="Code">💻</a></td>
   </tr>
 </table>
 

diff --git a/README.rst b/README.rst
diff --git a/docs/source/_static/css/external-links.css b/docs/source/_static/css/external-links.css
@@ -0,0 +1,15 @@
+/* Add :after icon to links to other pages */
+.external::after {
+    /*
+     * \00A0 is a "no break space" character that IS a space, but cannot be
+     * line-wrapped to a new line.
+     */
+    content: "\00A0[↪]";
+    /*
+     * Different fonts render unicode differently. By default, the "↪"
+     * shows up as an emoji which is quite ugly. The FastAPI docs use
+     * the Roboto font to achieve theirs. monospace works as well but it
+     * appears small on that case.
+     */
+    font-family: Roboto, Arial;
+}
diff --git a/docs/source/_static/js/remove-readthedocs-versions.js b/docs/source/_static/js/remove-readthedocs-versions.js
@@ -0,0 +1,16 @@
+const READTHEDOCS_SIDEBAR_ELEMENT_ID = "furo-readthedocs-versions";
+
+const remove_readthedocs_element = () => {
+    const element = document.getElementById(READTHEDOCS_SIDEBAR_ELEMENT_ID);
+    try {
+        element.parentNode.removeChild(element);
+    } catch (e) {
+        // pause and try again
+        console.log(e);
+        setTimeout(remove_readthedocs_element, 400);
+    }
+}
+
+window.onload = () => {
+    remove_readthedocs_element()
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -17,6 +17,7 @@
 import platform
 import sys
 from pathlib import Path
+from typing import Any, Dict
 
 THIS_DIR = Path(__file__).parent.resolve()
 ROOTSKI_DIR = (THIS_DIR / "../../rootski_api").resolve().absolute()
@@ -41,7 +42,7 @@
 # ones.
 extensions = [
     # tabs, cards, grid system, fontawesome/octicon icons and more
-    "sphinx_panels",
+    # "sphinx_panels",
     # places metadata in the <head> element on each page for social media
     "sphinxext.opengraph",
     # enable writing in markdown rather than reStructuredText
@@ -76,6 +77,12 @@
 # fontawesome icons
 # html_css_files = ["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css"]
 
+# paths relative to _static/
+html_css_files = ["css/external-links.css"]
+html_js_files = [
+    "js/remove-readthedocs-versions.js",
+]
+
 
 def is_mac_os():
     """Return ``True`` if this script is being run on MacOS."""
@@ -118,10 +125,63 @@ def is_mac_os():
 
 # -- Options for HTML output -------------------------------------------------
 
+html_favicon = "favicon.ico"
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = "furo"
+html_title = "Knowledge Base"
+language = "en"
+
+html_css_files += [
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
+]
+
+html_theme_options: Dict[str, Any] = {
+    # "announcement": "<em>Important</em> announcement!",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/rootski-io/rootski",
+            "html": "",
+            "class": "fab fa-github fa-2x",
+        },
+        {
+            "name": "LinkedIn",
+            "url": "https://www.linkedin.com/company/rootski/",
+            "html": "",
+            "class": "fab fa-linkedin fa-2x",
+        },
+        {
+            "name": "YouTube Playlist",
+            "url": "https://www.youtube.com/playlist?list=PLwF2z4Iu4rabmY7RbRNetjZprLfe8qWNz",
+            "html": "",
+            "class": "fab fa-youtube fa-2x",
+        },
+        {
+            "name": "Slack",
+            "url": "https://join.slack.com/t/rootskiio/shared_invite/zt-13avx8j84-mocJVx5wFAGNf5wUuy07OA",
+            "html": "",
+            "class": "fab fa-slack fa-2x",
+        },
+    ]
+}
+
+# configure the "pencil" (edit in GitHub) button; we must pretend that
+# we use READTHEDOCS to do this, because the Furo theme only officially
+# supports ReadTheDocs+GitHub for this feature as of March 2022.
+html_context = {}
+html_context["READTHEDOCS"] = True
+html_context["current_version"] = "latest"
+html_context["conf_py_path"] = "/docs/source/"
+html_context["display_github"] = True
+html_context["github_user"] = "rootski-io"
+html_context["github_repo"] = "rootski"
+html_context["github_version"] = "trunk"
+html_context["slug"] = "rski"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/source/favicon.ico b/docs/source/favicon.ico
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,22 +1,14 @@
-======================================================
-`rootski.io <https://www.rootski.io>`_ Knowledge Base
-======================================================
-
-
-:fa:`folder`
-
-.. include:: ../../README.rst
-
-
-.. drawio-image:: /_static/apps.drawio
-  :format: png
-
+==========================================================================
+The rootski Knowledge Base
+==========================================================================
 
 .. toctree::
   :hidden:
   :maxdepth: 1
 
   Home <self>
+  Onboarding <rst/onboarding/index>
+  Architecture & Tech Stack <rst/architecture/index>
 
 .. toctree::
   :hidden:
@@ -25,3 +17,175 @@
 
   Backend API Reference <rootski-api-reference>
   Infrastructure as Code Reference <iac-reference>
+
+.. .. image:: ./breakdown-window.svg
+..    :alt: russian word broken into roots
+
+.. repository badges
+.. raw:: html
+
+   </br>
+
+   <!-- badges:
+   - build pass/fail (built into GitHub)
+   - coverage percentage (provided by codecov) -->
+   <img alt="build" src="https://github.com/rootski-io/rootski/actions/workflows/rootski-ci.yml/badge.svg" />
+   <a href="https://codecov.io/gh/rootski-io/rootski">
+      <img alt="codecov" src="https://codecov.io/gh/rootski-io/rootski/branch/trunk/graph/badge.svg?token=YZJ0UFXNU3">
+   </a>
+   <br />
+   <br />
+
+Helpful Links
+-------------
+
+.. directive to force insert some spaces
+.. |tab| raw:: html
+
+   &nbsp;&nbsp;
+
+.. directives to insert font-awesome icons; see conf.py:html_css_files
+.. |rootski| raw:: html
+
+   <i class="fab fa-r fa-2x" style="color: #03a9f4"></i>
+
+.. |youtube| raw:: html
+
+   <i class="fab fa-youtube fa-2x" style="color: red"></i>
+
+.. |aws| raw:: html
+
+   <i class="fab fa-aws fa-2x" style="color: orange"></i>
+
+.. |slack| raw:: html
+
+   <i class="fab fa-slack fa-2x" style="color: purple"></i>
+
+.. |clickup| raw:: html
+
+   <i class="fa-solid fa-bars-progress fa-2x" style="color: magenta"></i>
+
+.. |github| raw:: html
+
+   <i class="fab fa-github fa-2x" style="color: gray"></i>
+
+.. |linkedin| raw:: html
+
+   <i class="fab fa-linkedin fa-2x" style="color: #0077b5"></i>
+
+.. list-table::
+   :widths: 10 30 60
+
+   * - |rootski|
+     - `rootski.io <https://www.rootski.io/>`_
+     - The live application we're building!
+   * - |github|
+     - `GitHub repo <https://github.com/rootski-io/rootski>`_
+     - Leave us a star ⭐️. The codebase; everything is open-source except for the full rootski dataset.
+   * - |clickup|
+     - `ClickUp Board <https://sharing.clickup.com/l/h/4-30114956-1/80ea8d248c817f3>`_
+     - Kanban board and backlog of work being done on rootski.
+   * - |slack|
+     - `Slack <https://join.slack.com/t/rootskiio/shared_invite/zt-13avx8j84-mocJVx5wFAGNf5wUuy07OA>`_
+     - Chat for anything related to rootski, onboarding, and projects.
+   * - |youtube| |tab|
+     - `YouTube Playlist <https://www.youtube.com/playlist?list=PLwF2z4Iu4rabmY7RbRNetjZprLfe8qWNz>`_
+     - Training videos walking through the architecture, tools, and how to contribute to rootski.
+   * - |linkedin|
+     - `LinkedIn Page <https://www.linkedin.com/company/rootski/>`_
+     - Follow our page 🔔. This is the rootski company page where we share posts
+       promoting the contributors after each PR.
+   * - |aws|
+     - `AWS console <https://rootski.signin.aws.amazon.com/console>`_
+     - Sign in link for the rootski AWS account.
+
+
+Contributors ✨
+------------------
+
+rootski is developed by volunteers! This `emoji key <https://allcontributors.org/docs/en/emoji-key>`_
+labels the different types of contributions.
+
+Links to everyone's personal sites are on the `GitHub README <https://github.com/rootski-io/rootski>`_ 🙂.
+
+.. raw:: html
+    :file: ../../CONTRIBUTORS.md
+
+
+What is rootski?
+---------------------
+
+.. raw:: html
+
+    <iframe width="560" height="315" src="https://www.youtube.com/embed/_KYgVet_HEA"
+      title="YouTube video player" frameborder="0"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen>
+    </iframe>
+
+rootski is an open-source, full-stack AI application for learning Russian.
+
+The three reasons for open-sourcing the rootski project are to:
+
+1. make `rootski.io <https://www.rootski.io/>`_ development faster and more fun.
+
+2. create a public reference anyone can see of an production-grade A.I. application
+   made with the absolute best industry practices.
+
+   .. note:: If you'd like to see how rootski is built, check out the :ref:`Architecture & Tech Stack <architecture-page>`.
+
+3. **offer mentorship and real-world experience** to contributors at *any* experience level
+   that are hard to simulate on a solo personal project--whether that be in
+
+   - full-stack development
+   - deploying software in AWS
+   - developing data science models and "shipping" them
+   - UI/UX
+   - DevOps
+   - MLOps
+   - ... anything else that goes into making a A.I. application with a large user base 😃.
+
+   .. note::
+
+      If you would like to contribute, welcome 🎉 🎉!! Any experience level is welcome as long as you
+      are `willing to learn <https://www.linkedin.com/posts/eric-riddoch_im-willing-to-learn-candidates-for-ds-activity-6895803295609233408-dKmu>`_. Check out the :ref:`onboarding page <onboarding-page>`
+      get started.
+
+
+
+.. .. warning::
+
+..    **Disclaimer, please read!** Contributing is 100% "free labor" in the sense that
+..    Eric Riddoch owns the rootski project.
+
+..    Please *do* or please *don't* contribute based on what you think is best for your
+..    career and personal growth.
+
+..    The value of contributing to rootski is in getting to work on part of a real product,
+..    having mentorship, and experimenting with tools you don't use at your day job. Whether
+..    or not you're experienced, that "mentorship" looks exactly the way it would at a paid
+..    job: we're a bunch of non-experts working mostly asynchronously, some of us knowing more about certain
+..    technologies than others.
+
+..    For Eric, this project is about learning/mentoring and he'd rather move slowly so
+..    that people can learn rather than focus on exploiting people adding new features.
+
+..    Eric pays $20+/mo (sometimes $50) on this and earns nothing. If that ever changes,
+..    he will be clear about that. If anyone were to be paid to work on this, the project
+..    simply wouldn't be possible. Eric is happy if the work we're doing here does nothing
+..    more than give people career opportunities and help remove confusion about how "real"
+..    software is built.
+
+..    Many of the contributors make real sacrifices offering their time and mentorship
+..    working on this project. Please don't criticize our motives. We want you do do what's
+..    best for you.  This model for building a product was inspired by this
+..    `podcast interview with the creator of the Python discord channel
+..    <https://talkpython.fm/episodes/show/305/python-community-at-python-discord>`_.
+
+..    Eric finds their intentions to be genuine. Please know that for over a year,
+..    Eric has "sunk" many evenings and weekends mentoring engineers and has seen no
+..    personal "return on investment" outside of relationships; he will gladly continue
+..    to do so, time permitting.
+
+..    Feel free to reach out to any of the "Contributors" or "Friends" to ask them
+..    about their experience.