finished docs and tested build locally

docs/contributing/getting_started.ipynb → docs/contributing/contribution_guidelines.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Getting Started"
+    "# Contribution Guidelines"
    ]
   },
   {
@@ -53,10 +53,14 @@
    "source": [
     "There are multiple ways in which you can help us:\n",
     "- Found a bug in STARDIS? Report it to us!\n",
+    "\n",
     "- Caught a typo in documentation or want to make it better to understand? Edit it!\n",
+    "\n",
     "- Know how to fix an issue or add a new feature? Make a patch!\n",
+    "\n",
     "- Loved using STARDIS? Share it with others!\n",
-    "- Anything we missed to mention? Then, what are you waiting for!"
+    "\n",
+    "- Anything we missed to mention? Then, what are you waiting for!\n"
    ]
   },
   {

docs/contributing/editing_stardis.ipynb

@@ -11,25 +11,142 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now that you have installed STARDIS and hopefully set up everything you need, you can now get started on your first **Pull Request**."
+    "Now that you have installed STARDIS and hopefully set up everything you need, you can now get started on **your first Pull Request**."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## "
+    "## Before You Edit"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": []
+   "source": [
+    "There are several things you must do before you can start patching some bugs, fixing those typos, or adding that new feature."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Starting Your Environment"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "1) Launch your Bash terminal, either using the **terminal app on Mac** or the **WSL or Ubuntu application on Windows**  \n",
+    "\n",
+    "2) Navigate to your **Stardis directory**, using the commands `ls` to *list* directory options and `cd <directory_name>` to *change* to the given *directory*.\n",
+    "\n",
+    "3) Start your **Stardis Environment** by running the command `conda activate Stardis`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Branches"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "One of the main reasons we use Git is because of Git **Branches**. Branches are like off-shoots of main code, where you can make changes to a specific feature or file without immediately worrying about the broader implications of your changes. The main code is in a branch called `main` (great naming, right?)<!-- <<< Should this whimsy be removed?-->, and can be refered to as the *trunk*, because the other branches come off of it.\n",
+    "\n",
+    "Its important to keep in mind that when you want to start working on a new feature or change, **make a new branch for that change!** This way, when you make the Pull request to apply that change, the reviewers know exactly what your change does, and the proccess goes smoothly. \n",
+    "\n",
+    "- Make a new Branch with the command: `git branch my_branch_name`\n",
+    "\n",
+    "- Change to your new branch with the command: `git checkout my_branch_name`\n",
+    "\n",
+    "- To do both at once, use: `git checkout -b my_branch_name`\n",
+    "\n",
+    "It is good to name your branch after what you are changing in it. For example, the branch name used to make this documentation was `contribution_docs`, so an example from above would look like `git checkout -b contribution_docs`. Make sure to change to the `main` branch before making a new branch, that way you will have a fresh start to make your changes.\n",
+    "\n",
+    "Lastly, if you need a reminder on what branches you have made, you can use the command `git branch` to see a list."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## While You Edit"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "While you are clicking through directories, making changes to your hearts desire, there are some things to note.\n",
+    "\n",
+    "- The changes you make will only impact the version on STARDIS on your computer for now, so you don't have to worry about breaking anything.\n",
+    "\n",
+    "- After editing a file, make sure to press `ctrl`+`s` to save the file. Otherwise, nothing will be saved.\n",
+    "\n",
+    "- you can use the command `git status` to remind yourself what branch you are on and see what changes you have made. Do this often!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Apply Your Changes"
+   ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": []
+   "source": [
+    "Now that you have made your change, you can finally make a pull request! A pull request is essentially just a suggested change you think should be made to the functional code base of STARDIS. Once accepted, your work will be included in the version of STARDIS that everyone will use."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Don't be Scared!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You may be worried that your code doesn't work, your changes don't make sense, or that for some reason what you did is not good enough. **This is not the case, we promise!** A pull request can't break anything. If you did make any mistakes, then a pull request is how you can get suggestions and help. It never hurts to make a pull request, and changes can always be revised and edited, even after the initial request. \n",
+    "\n",
+    "If you are still concerned a PR isn't fully functional, you can always mark a pull request as a draft. To do this, go to the Github website, and find the new PR under either your account or on the STARDIS page. Open the pull request, and on the right side of the screen you should see an option to 'convert to draft'."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Make a Pull Request"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here are the steps you can take to make your first PR:\n",
+    "\n",
+    "1) Run the command `git add -A`\n",
+    "\n",
+    "2) Run the command `git commit -m '<explanation_of_your_pr>'`\n",
+    "    - example: git commit -m 'Typo fix in the quickstart notebook'\n",
+    "\n",
+    "3) Run the command `git push origin <my_branch_name>`\n",
+    "    - example: git push origin contribution_docs\n",
+    "\n",
+    "By doing this, the change you made will be pushed to your fork of STARDIS under your Github account. Next, you need to go to [the original STARDIS repository](https://github.com/tardis-sn/stardis) where you made your clone. There will be a yellow banner asking you to **Compare & Pull Request**.\n",
+    "\n",
+    "You will then need to fill out a form that goes with the PR where you explain your changes. Make sure to be specific in your explanation of the changes, as well as edit the 'type' field to indicate what your changes effect."
+   ]
   }
  ],
  "metadata": {

docs/contributing/starting_from_scratch.ipynb

@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This page will guide you through everything you need to do to start working on STARDIS, even if you have no prior experience or knowledge. mainly, this page will show you how to:\n",
+    "This page will guide you through everything you need to do to start working on STARDIS, even if you have **no prior experience or knowledge**. mainly, this page will show you how to:\n",
     "\n",
     "- Set up a linux Subsystem for Windows\n",
     "\n",
@@ -163,7 +163,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Here we go through some steps of the [STARDIS installation documentation](../../docs/installation.rst) in more detail. You can go try and run through installation on your own first, refering back here when/if you need to, or you can go through this section first before moving on to installation. The choice is yours!"
+    "Here we go through some steps of the STARDIS installation documentation in more detail. You can go try and run through installation on your own first, refering back here when/if you need to, or you can go through this section first before moving on to installation. The choice is yours!"
    ]
   },
   {
@@ -202,7 +202,9 @@
     "\n",
     "If you get stuck somewhere along the way, you can try\n",
     "- [Github's instructions for setting up a SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)\n",
+    "\n",
     "- Watching this [youtube walkthrough](https://www.youtube.com/watch?v=snCP3c7wXw0)\n",
+    "\n",
     "- Asking a generative AI for help (like [ChatGPT](https://chatgpt.com/)). AI can make mistakes, so be careful!"
    ]
   },
@@ -241,7 +243,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You should now be able to go through the [STARDIS installation documentation](../../docs/installation.rst). While everything you need to know should be there, here are some things to note:\n",
+    "You should now be able to go through the STARDIS installation documentation. While everything you need to know should be there, here are some things to note:\n",
     "\n",
     "1) before starting, you need to create a directory/folder for STARDIS to be stored in. To do so, run these commands in the Bash terminal:\n",
     "    - `cd ~` <-- *changes directory (cd) to the home directory*\n",
@@ -250,8 +252,11 @@
     "\n",
     "2) When setting up the STARDIS environment:\n",
     "    - Use the set of commands that use **Conda**, not Mamba.\n",
+    "\n",
     "    - You won't need to run `cd <path-to-stardis-directory>` if you ran the prior three commands in step 1, as you will already be in the STARDIS directory. Otherwise, change `<path-to-stardis-directory>` to the path to your STARDIS directory.\n",
+    "\n",
     "    - When replacing `{platform}` in the commands, use `osx-64` if you are on MacOS or `linux-64` if you are using WSL/Ubuntu on Windows.\n",
+    "    \n",
     "    - When coping commands into terminal, do so one at a time, and don't include the '$ ' at the start!\n",
     "\n",
     "3) When given the choice, follow the instructions under the **For Developers** section\n",
@@ -270,7 +275,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Through the course of setting up STARDIS, you had to copy many different commands into the Bash terminal. While many of these may seem alien or arbitrary now, over time you will learn more about what exactly these command do. But until then, it may be helpful to look up resources to learn more about Bash commands.\n",
+    "Through the course of setting up STARDIS, you had to copy many different commands into the Bash terminal. While many of these may seem alien or arbitrary now, over time you will learn more about what exactly these commands do. But until then, it may be helpful to look up resources to learn more about Bash commands.\n",
     "\n",
     "[Codecademy's](https://www.codecademy.com/learn) courses on learning python and command line are great resources for understanding the basics you'll need to work on STARDIS. Many other resources exist on the internet for learning these skills, we have just found Codecademy covers much of what you'll need to know for editing STARDIS. Namely, we recommend:\n",
     "\n",
@@ -280,6 +285,11 @@
     "\n",
     "\\* While 'Learn the Command Line' is not a free course, it can most likely be completed during your Codecademy free trial. Again, many other free resources exist out there, so feel free to choose a different option!"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
   }
  ],
  "metadata": {

docs/index.rst

@@ -23,6 +23,13 @@ This is the documentation for STARDIS.
    Changing Parameters <Changing_Parameters/Changing_Parameters>
    Rotation Broadening <rotation_broadening/rotation_broadening>
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Contributing to STARDIS
+
+   Contribution Guidelines <contributing/contribution_guidelines>
+   Starting from Scratch <contributing/starting_from_scratch>
+   Editing Stardis <contributing/editing_stardis>
 
 Indices and tables
 ==================