Add Contributor Section

README.md

@@ -1,57 +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)
-
-## 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.

dependencies

@@ -1,4 +1,3 @@
 texlive-xetex
 latexmk
-jq
 fonts-roboto

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 a information base for students and mentors to make informed decisions.

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 = [
@@ -278,6 +278,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",

docs/source/contrib/guidelines/guidelines.rst

@@ -0,0 +1,39 @@
+Contribution Guidelines
+=======================
+
+Contributors are the life blood 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 desrcribe 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)
+

docs/source/contrib/index.rst

@@ -0,0 +1,34 @@
+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.

docs/source/contrib/style_guide/style-guide.rst

@@ -0,0 +1,15 @@
+FTC Docs Style Guide
+====================
+
+.. note:: The following is modeled after the `FRC Docs Style Guide <https://docs.wpilib.org/en/stable/docs/contributing/frc-docs/style-guide.html>`_.
+
+
+Filename
+--------
+
+Use only lowercase alphanumeric characters and - (minus) symbol.
+
+For documents that will have an identical software/hardware name, append “Hardware” or “Software” to the end of the document name. IE, ultrasonics-hardware.rst
+
+Suffix filenames with the .rst extension.
+

docs/source/contrib/tutorials/codespaces/codespaces.rst

@@ -0,0 +1,34 @@
+Codespaces
+==========
+:bdg-secondary:`Information`
+
+What is Codespaces?
+-------------------
+
+Codespaces is a cloud-hosted development environment that you can access from anywhere. 
+It comes with a pre-configured Visual Studio Code environment and a containerized runtime that matches your development environment. 
+You can use Codespaces to develop in a browser, or by using the Visual Studio Code Remote - Codespaces 
+extension in your local Visual Studio Code instance. 
+
+Why use Codespaces?
+-------------------
+
+Codespaces is a great way to develop in a consistent environment, no matter where you are. It 
+also allows you to develop on a device that might not have the resources to run your development 
+environment locally. It also allows you to sidestep the need to install and configure your 
+development environment on a new machine.
+
+Who should use Codespaces?
+---------------------------
+
+Codespaces is our recommended development environment for all developers. It is especially 
+useful for developers who need to work on multiple machines, or who are not comfortable with 
+setting up their development environment and the troubleshooting that comes with it.
+
+Downside of Codespaces
+----------------------
+
+Codespaces is a paid service, and you will be billed for the resources you use. However, 
+GitHub currently offers GitHub Free tier users **120 Core hours** and GitHub Pro tier users **180 
+Core hours** per month for free. To learn more about Codespaces pricing, visit 
+`GitHub Documentation <https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces>`_.

docs/source/contrib/tutorials/create_codespace/create-codespace.rst

@@ -0,0 +1,34 @@
+Creating a Codespace
+=====================
+:bdg-success:`Repeat` :bdg-info:`Codespaces`
+
+For every new branch you make in your repository, you must create a new codespace. 
+This is a virtual environment that will allow you to run your code and test it before merging it into the main branch. 
+It may take a few minutes to create the codespace, but once it is created, you can access it from the browser and subsequent access will be much faster.
+
+Steps
+-----
+
+1. Open your **forked** repository in GitHub.
+2. On the left side of the page select the branch you want to work on.
+
+.. figure:: images/select-branch.png
+   :alt: Select branch
+   :align: center
+   :width: 100%
+
+1. Click on the green "Code" button and select "Create codespace on ``<BRANCH>``".
+
+.. figure:: images/select-cs.png
+   :alt: GH Code Menu
+   :align: center
+   :width: 100%
+
+.. figure:: images/create-cs.png
+   :alt: GH Code Menu
+   :align: center
+   :width: 100%
+
+2. Wait for the codespace to be created. This may take a few minutes.
+3. Once the codespace is created, you will be taken to the codespace in your browser.
+4. Enter ``CTRL + SHIFT + B`` to build the project.

docs/source/contrib/tutorials/github_repo/github-repo.rst

@@ -0,0 +1,61 @@
+Getting to know the GitHub Repo
+===============================
+:bdg-secondary:`Information`
+
+.. note::
+   It is assumed that you have created a GitHub account and been given the proper 
+   permissions to work within this repository for training. If you can read this,
+   you probably have, but double-check with your friendly FTC Support person.
+
+GitHub is a website where people and organizations can store projects in what's
+known as a "repository". Some repositories can be public, meaning anyone can
+see the content within it, and some are private. The rST-Primer you're working on
+is a private repository, which can only be seen and accessed by those given
+access within the organization. *FIRST* Tech Challenge has several public and
+private repositories for software projects within the organization.
+
+Understanding the rST-Primer Repo
+---------------------------------
+
+The GitHub ``rst-primer`` repository can be found on GitHub at the following address:
+
+-  https://github.com/FIRST-Tech-Challenge/rst-primer/
+
+The GitHub repository is where all of our documentation source files and
+project content is kept. Figure 1 shows what the main code page for the
+``rst-primer`` repository looks like. 
+
+.. figure:: images/rst-primer_repo.png
+   :width: 80%
+   :align: center
+   :alt: Figure 1 rst-primer GitHub Repo
+
+   Figure 1: rst-primer GitHub Repository
+
+This main **code page** is where you'll do most of your work. It's called a **code
+page** because by default the ``< > Code`` tab of the repository is selected,
+and this is the page that we're currently viewing. For software projects, the
+**code page** is where code is stored; for us, this is where our *content* is
+stored. There are several different tabs, but we only really care about the
+first four:
+
+1. ``< > Code`` - The **Code page** shows us the file structure of our repository and
+   also allows us to view and edit files.
+
+2. ``Issues`` - The **Issues page** shows us "issues" that any user can submit. These 
+   issues are generally feature request (like "Please add emojis to the document workflow")
+   or bug reports (like "When I use dropdowns, my document errors out."). Issues are 
+   not meant to be discussions, but very specific tasks that need to be addressed.
+
+3. ``Pull Requests`` - The **Pull Requests page** shows us "Pull Requests"; for this 
+   project, these will be requests to merge changes into the main branch. Don't worry
+   about this page just now, we'll cover **Pull Requests** in more detail later.
+
+4. ``Discussions`` - The **Discussions page** is where users can visit and ask 
+   questions or get help on topics. This is meant to be an open discussion area for the
+   repository. This area is similar to a forum, but specifically for ``rst-primer``.
+
+The ``< > Code`` tab will be the tab that we will spend most our time in, as this 
+is where we manage *branches*, view and edit files, and perform most of our basic
+functions.
+

docs/source/contrib/tutorials/index.rst

@@ -0,0 +1,23 @@
+Tutorials
+============
+
+These are a couple tutorials that will walk you through the process of creating and editing 
+in FTC Docs.
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    overview/overview
+    codespaces/codespaces
+    github_repo/github-repo
+    make_fork/make-fork
+    update_fork/update-fork
+    setup/setup
+    make_branch/make-branch
+    create_codespace/create-codespace
+    switch_branch/switch-branch
+    make_rst/index
+    setup_credentials/setup-credentials
+    make_pr/make-pr
+