Move Documentation from reST to Markdown (#114)

Author: JasonGrace2282

docs/source/conf.py

@@ -43,6 +43,14 @@
     "sphinxcontrib_django",
 ]
 
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "dollarmath",
+    "html_admonition",
+    "linkify",
+]
+
 add_function_parentheses = False
 
 # Automatically generate stub pages when using the .. autosummary directive

docs/source/contact.rst docs/source/contact.mddocs/source/contact.rst renamed to docs/source/contact.md

@@ -1,6 +1,4 @@
-##############
-Contacting Tin
-##############
+# Contacting Tin
 
 If you need to get in touch with the Tin team, you can email us at tin@tjhsst.edu
 

docs/source/contributing.md

@@ -0,0 +1,29 @@
+# Contributing
+
+```{note}
+Tin is a django project. As such, some knowledge of
+python and django is recommended to contribute anything
+more than a trivial patch.
+```
+
+Thank you for your interest in contributing to Tin!
+We accept contributions in various areas, some of which are
+detailed below:
+
+- Code Maintenance
+- New Features
+- Writing Tests
+- Website and Graphical Design
+
+Contributing to projects can often be a little confusing,
+so here are some guides to help you get started with whatever
+you're interested in contributing!
+
+```{toctree}
+:maxdepth: 2
+
+contributing/setup
+contributing/docs
+contributing/tests
+contributing/conventions
+```

docs/source/contributing.rst

@@ -1,50 +1,47 @@
-###########
-Conventions
-###########
-
-Pre-Commit
-----------
-Tin uses ``pre-commit`` to ensure similarly formatted code
-across the codebase. Once you have installed pre-commit (see :ref:`dev-setup`),
-run
+# Conventions
+
+## Pre-Commit
 
-.. code-block:: bash
+Tin uses `pre-commit` to ensure similarly formatted code
+across the codebase. Once you have installed pre-commit (see {ref}`dev-setup`),
+run
 
-   pre-commit install
+```bash
+pre-commit install
+```
 
-To install ``pre-commit`` hooks into git. Now, every time you commit, ``pre-commit``
+To install `pre-commit` hooks into git. Now, every time you commit, `pre-commit`
 will run your code against a formatter and linter, making your contribution
 easier to review.
 
-Commits
--------
+## Commits
+
+### Content
 
-Content
-~~~~~~~
 Tin doesn't follow a specific naming convention for commits; however,
 if your commits are named well and are easy to review individually,
 you are likely to receive a response faster. For example, a PR with commits like
 
-* Add CI + Config for Javascript Formatter
-* Autoformatted Javascript code
+- Add CI + Config for Javascript Formatter
+- Autoformatted Javascript code
 
 Will likely be reviewed faster than a PR with a single commit like
 
-* Add Javascript Formatter and format code
+- Add Javascript Formatter and format code
+
+### Syncing with master
 
-Syncing with master
-~~~~~~~~~~~~~~~~~~~
 At some point in your PR, it's likely your branch and the master branch will diverge,
 and at this point you'll have to either merge master into your branch, or rebase your changes
 on top of master. *Tin prefers that you rebase*, in order to preserve linear history.
 
 As a quick review on how to rebase with upstream, you can do
 
-.. code-block:: bash
+```bash
+git pull --rebase https://github.com/tjcsl/tin master
+```
 
-   git pull --rebase https://github.com/tjcsl/tin master
+### Signing Commits
 
-Signing Commits
-~~~~~~~~~~~~~~~
 This is not strictly a requirement, but it's highly recommended to sign commits.
 It's a good developer habit, and makes it a little nicer to review your changes.

docs/source/contributing/conventions.rst docs/source/contributing/conventions.mddocs/source/contributing/conventions.rst renamed to docs/source/contributing/conventions.md

@@ -0,0 +1,62 @@
+# Docs
+
+Tin uses [Sphinx](https://www.sphinx-doc.org/) to build its documentation.
+The actual content is written in reStructuredText (`.rst`) format, and can
+be found in the `docs/source` folder at the [Tin Github](https://github.com/tjcsl/tin).
+
+## Building Docs
+
+First, you must have a local copy of Tin on your computer (see {ref}`dev-setup`).
+After that, `cd` into the `docs` folder.
+
+Next, run the following commands based on your operating system
+
+```bash
+make.bat html  # Windows
+make html  # *nix
+```
+
+The first time you build the docs, it may take some time. On future builds,
+the html will be cached.
+
+## Writing Documentation
+
+Written documentation is in the Markdown format.
+
+When writing a docstring for a method, attribute, or a function, we use the [Google style docstrings](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods).
+Do NOT include the type of a parameter in the docstring: that's redundant and harder to maintain. Instead,
+prefer typehinting the actual typehint in the function, and sphinx will automatically parse that.
+
+For example,
+
+```python
+# BAD
+def my_function(x):
+   """
+   A BAD docstring for my_function
+
+   Args:
+     x (int): the first parameter
+   """
+   return x+1
+
+# GOOD! Note how the parameter has the typehint, not the docstring
+def my_function(x: int):
+   """
+   A good docstring for my_function
+
+   Args:
+     x : the first parameter
+   """
+   return x+1
+```
+
+## Tips and Tricks
+
+Sometimes Sphinx will do some weird stuff and things will stop working nicely.
+In this case, a simple `make cleanall` (or `make.bat cleanall` for Windows) should do the trick.
+
+```{warning}
+`make.bat cleanall` is \_untested\_ on Windows, be careful when using it. You can alternatively
+use `make.bat clean` and remove the contents of `docs/source/reference`.
+```

docs/source/contributing/docs.md

@@ -0,0 +1,74 @@
+(dev-setup)=
+
+# Setting up a development environment
+
+To begin with, you will need to have [git](https://git-scm.com/) installed on your computer.
+You will also need a GitHub account.
+
+First, [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository)
+tin. Then you can clone tin onto your computer with
+
+```bash
+git clone https://github.com/YOUR_GITHUB_USERNAME/tin
+```
+
+From here, you can either use a local setup, or use Docker. Check out the
+relevant sections.
+
+## Docker
+
+If you prefer, you can run the development setup with [Docker](https://www.docker.com/). To do so,
+`cd` into the project directory and run:
+
+```
+docker compose build
+docker compose up
+```
+
+To create testing users and apply migrations, run the below command in a separate terminal:
+
+```
+./scripts/docker_setup.sh
+```
+
+## Local Setup
+
+To set up your environment locally, you will need to install the following:
+
+- [python](https://www.python.org/downloads/) (3.11)
+- [uv](https://docs.astral.sh/uv/)
+
+Then, run these commands:
+
+```
+uv run manage.py migrate
+uv run manage.py create_debug_users
+```
+
+Now you're all set! Try running the development server
+
+```bash
+uv run manage.py runserver
+```
+
+Head on over to [http://127.0.0.1:8000](http://127.0.0.1:8000), and login
+as `admin` and the password you just entered.
+
+In order to actually submit code, there are some more steps. First,
+you'll need to install [redis](https://redis.io/download).
+
+You'll also need to start the celery worker. This can be done
+by running the following command in a separate terminal:
+
+```
+uv run celery -A tin worker --loglevel=info
+```
+
+## Final Steps
+
+After that, you'll want to create a course and an assignment in the course.
+After saving the assignment, you can hit "Upload grader" to add a grader -
+the simplest example of a grader is located in `scripts/sample_grader.py`.
+
+Now you can try making a submission, and as long as your submission doesn't throw an error you
+should get a 100%! Congrats on your brand new 5.0 GPA!