FIRST-Tech-Challenge · texasdiaz · Feb 17, 2025 · Sep 7, 2022 · Sep 7, 2022 · Sep 7, 2022
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,9 @@
 # Created by https://www.toptal.com/developers/gitignore/api/python,jupyternotebooks
 # Edit at https://www.toptal.com/developers/gitignore?templates=python,jupyternotebooks
 
+### Mac OS ###
+*.DS_Store
+
 ### JupyterNotebooks ###
 # gitignore template for Jupyter Notebooks
 # website: http://jupyter.org/

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -3,6 +3,7 @@
         "lextudio.restructuredtext",
         "lextudio.restructuredtext-pack",
         "trond-snekvik.simple-rst",
-        "ms-python.python"
+        "ms-python.python",
+        "swyddfa.esbonio"
     ]
 }
diff --git a/README.md b/README.md
@@ -1,63 +1,13 @@
 *FIRST* Tech Challenge Documentation Project
 ==========================================
+
 ![Build](https://readthedocs.com/projects/first-tech-challenge-ftcdocs/badge/?version=latest) ![Link-Check](https://github.com/FIRST-Tech-Challenge/ftcdocs/actions/workflows/link-check.yaml/badge.svg)
 
 This GitHub project is a work-in-progress for FTC documentation.
 
-# Contributing
-
-## Prerequisites
-
-- GitHub Account
-- Git Installed on Local Machine (for local method)
-
-### Windows software dependencies (typically preinstalled on a Linux distro)
-
-- GitForWindows: https://gitforwindows.org/
-- Chocolatey for installing make: https://chocolatey.org/install#individual
-- make: https://community.chocolatey.org/packages/make
-
-## Local Method
-
-1. Create fork of FtcDocs Project as shown [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo) keeping the name of the repo the same
-2. Clone fork of project replacing `<NAME>` with your username
-
-      `git clone https://github.com/<NAME>/ftcdocs.git`
-3. Install Python from [here](https://www.python.org/downloads/)
-4. Install Pip following [these](https://pip.pypa.io/en/stable/installation/) instructions
-5. Change directory to root project and install dependencies
-    - `cd ftcdocs`
-    - `pip install -r docs/requirements.txt`
-6. Make desired changes to project. Remember to follow style guide shown [here](https://docs.wpilib.org/en/stable/docs/contributing/frc-docs/style-guide.html)
-7. Install dependencies for PDF
-    - Ubuntu/Debian: `xargs -a dependencies sudo apt install -y`
-    - Windows: Install MiKTeX from [here](https://miktex.org/download)
-8. Build project by executing following commands in `docs\` folder of project
-    - HTML: `make html`
-    - Autobuild HTML: `make autobuild`
-    - PDF: `make latexpdf`
-    - Link: `make linkcheck`
-9. View Result (html)
-    - Open `docs\build\html\index.html` in a browser of your choice
-    - To create local http server execute `python3 -m http.server 7350` in `docs\build\html\index.html` and view result [here](http://localhost:7350). If you are using the Autobuild option this server will be automatically created and updated with most changes to rst files. Some changes will not be transferred like images and will require a `make clean`.
-10. Commit changes and push after desired result has been achieved
-    - `git commit -a -m <MESSAGE>` replace <MESSAGE> with your commit message
-    - `git push`
-11. [Create](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) a Pull Request to upstream repository. Make sure to be concise in your PR title and description. 
-
-## Cloud Method
+The website is available at https://ftc-docs.firstinspires.org
 
+# Contributing
 
-1. Create fork of FtcDocs Project as shown [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
-2. Ideally you should follow a feature based branch system. This means that you should create a new branch every time you are thinking of adding a new feature. This will insure that the main branch stays identical to upstream.
-    1. Click the drop down menu that says the branch you are currently working on (default is main) towards the top but slightly to the left
-    2. Type in what you wish to name your branch. It should be short and concise while also being able to convey to others what feature this branch has
-    3. Next click `Create branch: [name of branch] from ‘main’`
-3. Although you can view changes made in the Github preview this can be incorrect and is often incomplete. To give an accurate view of what your changes look like you will want to make your own Read The Docs site to preview your changes. To do this follow the instructions given [here](https://docs.readthedocs.io/en/stable/tutorial/index.html) forgoing the "Preparing your project on GitHub" and not going beyond "Checking the first build". Name your site `<USERNAME>-ftcdocs`
-4. To change the branch that RTD builds on do the following
-    1. Go to `https://readthedocs.org/dashboard/<USERNAME>-ftcdocs/advanced/` after replacing `<USERNAME>` with your username
-    2. Click your user in the top right corner
-    3. Change Default branch to the branch you want to build off of
-    ![demo](https://media.discordapp.net/attachments/836704905364373547/992042745952751626/unknown.png)
-5. Make desired changes to forked project via Github Web Editor. This is as simple as clicking edit icon after viewing any given file. Remember to follow style guide shown [here](https://docs.wpilib.org/en/stable/docs/contributing/frc-docs/style-guide.html)
-6. View Changes on created RTD site by visiting `https://<USERNAME>-ftcdocs.readthedocs.io/en/latest/` after replacing `<USERNAME>` with your username
+We are always looking for help improving FTC Docs. For more infomration on contributing 
+consult the [contributing section](https://ftc-docs.firstinspires.org/contrib/index.html) in FTC Docs.
diff --git a/dependencies b/dependencies
@@ -1,5 +1,3 @@
 texlive-xetex
 latexmk
-jq
-unzip
 fonts-roboto
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -9,5 +9,6 @@ git+https://github.com/FIRST-Tech-Challenge/ftcdocs-helper@main#subdirectory=coo
 sphinx-sitemap==2.3.0
 python-git-info==0.8.3
 sphinxcontrib-mermaid==0.9.2
+sphinx-hoverxref==1.3.0
 sphinxext-rediraffe==0.2.7
-git+https://github.com/FIRST-Tech-Challenge/ftcdocs-helper@main#subdirectory=linkcheckdiff
+git+https://github.com/FIRST-Tech-Challenge/ftcdocs-helper@main#subdirectory=linkcheckdiff
diff --git a/docs/source/common/mission.rst b/docs/source/common/mission.rst
@@ -0,0 +1,6 @@
+FTC Docs aims to provide a comprehensive documentation base for *FIRST* Tech Challenge teams and mentors. 
+It is a community-driven project, hosted and moderated by FIRST Tech Challenge staff, 
+and we welcome contributions from all teams and mentors. It is our hope that this project will help to 
+make the community more connected and informed while reducing the fragmentation of documentation present 
+in *FIRST* Tech Challenge. The information provided is not meant to endorse any specific method or approach, 
+but rather to provide an information base for students and mentors to make informed decisions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -11,8 +11,8 @@
 author = 'FIRST Tech Challenge'
 license = 'BSD 3-Clause'
 
-release = '0.2'
-version = '0.2.0'
+release = '0.3'
+version = '0.3.0'
 # -- General configuration
 
 extensions = [
@@ -29,10 +29,15 @@
     'sphinxcontrib.googleanalytics',
     'sphinxcontrib.cookiebanner',
     'sphinxcontrib.mermaid',
+    'hoverxref.extension',
     "sphinxext.rediraffe",
     "ftcdocs_linkcheckdiff",
 ]
 
+# Options for HoverXRef extension
+
+hoverxref_roles = ['term']
+
 autosectionlabel_prefix_document = True
 default_dark_mode = False
 todo_include_todos = False
@@ -284,6 +289,7 @@
 # GitHub links with Javascript Anchors cannot be detected by linkcheck
 # Solidworks returns 403 errors on too many web pages. Thanks, buddy.
 # As of 7/13/23, april.eecs.umich.edu has an expired certificate
+
 linkcheck_ignore = [
    r'https://my.firstinspires.org/Dashboard/', 
    "https://ftc-ml.firstinspires.org",
@@ -310,7 +316,7 @@
 if(os.environ.get("BOOKLETS_BUILD") == "true"):
     print('Building booklets')
     latex_documents = [
-	('ftc_ml/index', "ftc_ml.tex", "FTC Machine Learning", author, "manual"), # FTC ML
+        ('contrib/index', "contrib.tex", "Contributing to FTC Docs", author, "manual"), # Contributing
         ('programming_resources/index', "prgrm_res.tex", "FTC Programming Resources", author, "manual"), # Programming Resources
         ('programming_resources/android_studio_java/Android-Studio-Tutorial', 'android_studios.tex', 'Android Studio Guide', author, "manual"), # Android Studio
         ('programming_resources/onbot_java/OnBot-Java-Tutorial', "onbot_java.tex", 'OnBot Java Guide', author, "manual"), # OnBot Java
@@ -323,7 +329,6 @@
         ('manufacturing/3d_printing/index', '3d_printing.tex', '3D Printing Guide', author, "manual"), # 3D Printing
         ('hardware_and_software_configuration/configuring/managing_esd/managing-esd', 'esd.tex', 'Managing Electrostatic Discharge', author, "manual"), # ESD
     ]
-
 
 def setup(app):
     app.add_css_file("css/ftc-rtd.css")

diff --git a/docs/source/contrib/guidelines/guidelines.rst b/docs/source/contrib/guidelines/guidelines.rst
@@ -0,0 +1,51 @@
+Contribution Guidelines
+=======================
+
+Contributors are the lifeblood of the project. We welcome contributions but remind everyone to 
+be a :doc:`Gracious Professional </gracious_professionalism/gp>`.
+
+Creating a PR
+--------------
+
+PRs should be made to the `FTC Docs <https://github.com/FIRST-Tech-Challenge/ftcdocs>`_ repo on GitHub. Your 
+title should aim to describe the purpose of your PR in a *concise* manner. For more information on creating a 
+PR, see 
+`this <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_
+
+
+Creating an Issue
+------------------
+
+There are two types of issues: bugs and feature requests. A bug report is an issue that describes a problem with the 
+documentation. A feature request is an issue that describes a new feature that should be added to the documentation. 
+Before creating either make sure to check for duplicates. If you find a duplicate, comment on the issue and add your 
+input where possible. If possible we would love to see a PR that fixes the issue. If you are unsure how to fix the issue 
+that is perfectly alright. 
+
+Bug Reports
+-------------
+
+* A description of the bug
+* Expected behavior
+* Steps to reproduce the bug (If applicable)
+* Screenshots (If applicable)
+
+Feature Requests
+------------------
+
+* A description of the feature
+* Why you think this feature should be added
+* Screenshots (If applicable)
+
+Colophon
+--------
+
+FTC Docs is built with `Sphinx <https://www.sphinx-doc.org/>`__ using a `theme <https://github.com/readthedocs/sphinx_rtd_theme>`__ provided by `Read the Docs <https://readthedocs.org/>`__.
+
+The `Dark theme <https://github.com/FIRST-Tech-Challenge/ftcdocs-helper/tree/main/sphinx_rtd_dark_mode_v2>`__ is provided by the FTC Docs development team.
+
+.. We might wish to state what version of Sphinx we use and other version info.
+   This is also where we could declare what versions of HTML, XML, CSS we target. Perhaps what browsers we target. 
+   (X)HTML, CSS, or usability standards compliance information and links to website validation tests. This used to be a thing, not so much anymore.
+   Perhaps that we are WCAG compliant someday.
+
diff --git a/docs/source/contrib/index.rst b/docs/source/contrib/index.rst
@@ -0,0 +1,33 @@
+Contributing to FTC Docs
+=========================
+
+.. toctree::
+    :hidden:
+
+    guidelines/guidelines
+    style_guide/style-guide
+    workflow/workflow
+    tutorials/index
+
+
+Mission Statement
+-----------------
+
+.. include:: /common/mission.rst
+
+- :doc:`Contribution Guidelines <guidelines/guidelines>`
+- :doc:`Style Guide <style_guide/style-guide>`
+- :doc:`FTC Docs Workflow <workflow/workflow>`
+- :doc:`Tutorials <tutorials/index>`
+
+
+====
+
+FTC Docs is maintained by:
+
+- Daniel Alfredo Diaz, Jr.
+- Elizabeth Gilibert
+- Chris Johannesen, Westside Robotics
+- Uday Vidyadharan, MFW Team 7350 Watt's NXT?
+
+A special thanks to everyone who has contributed to this project.