WIP: Proposed additional documentation for the website.

.gitignore

@@ -1,5 +1,6 @@
 **.DS_Store
 **.vscode/
 **.pytest_cache/
-**.venv/
-**src/
+**venv/
+**src/
+**docs/

source/developer/dev-website-contribute.md

@@ -0,0 +1,67 @@
+# Website contributing guide
+The website is written in markdown format, created through sphinx. These markdown files can be edited/created/deleted to update/create/remove pages.
+
+In order to contribute to the website, a series of steps should be followed:
+
+<ol>
+  <li>Download the code from the website repository</li>
+  <li>Create a new branch based off the Dev branch.</li>
+  <li>Make the desired changes to the markdown files located within the source directory.</li>
+  <li>Preview your changes through: 
+    <ul>
+      <li>your IDE of choice (look it up for your ide. 
+<a href="https://code.visualstudio.com/docs/languages/markdown#_markdown-preview">Visual Studio Code Example</a>)</li>
+      <li>building the website through sphinx and then viewing the html</li>
+      <li>any other markdown viewing program</li>
+    </ul>
+  </li>
+  <li>Upload your changes to a separate branch</li>
+  <li>Create a pull request to the Dev branch</li>
+  <li>(Optional) Create a pull request from the Dev branch into the Main branch whenever you are ready for the website to be updated</li>
+</ol> 
+
+## Adding images to your page
+Every image that is contained within the website should be stored within the `_static` folder located within source.
+In order to then use that image you must reference it's location within the markdown page.
+
+As an example:
+```
+<div align="center">
+	<img align="center" src="../_static/img/Iilluminator.jpg" width="500">
+</div>
+```
+
+Which results in a centered image, of width 500 like so:
+<div align="center">
+	<img align="center" src="../_static/img/illuminator.jpg" width="500">
+</div>
+
+
+## Building and previewing the website through sphinx
+Building and previewing the website before it is uploaded on github is highly recommended. In order to create this preview a series of steps must be followed. Example over command line interface:
+
+<ol>
+  <li>Ensure you are in the correct directory with your terminal (your directory should see README.md and source)</li>
+  <li>Prepare your environment:
+    <ol>
+      <li>python3 -m venv .venv</li>
+      <li>Activate your work environment:
+        <ul>
+            <li>MacOS & Linux: source .venv/bin/activate</li>
+            <li>Windows: .venv\Scripts\activate </li>
+        </ul>
+        </li>
+      <li>pip install -r source/requirements.txt</li>
+      <li>pip install illuminator --no-deps</li>
+    </ol>
+  </li>
+  <li>Make your changes (if you added a new page make sure to add it to index.rst so its visible in the side-bar)</li>
+  <li>Build using sphinx:
+    <ul>
+        <li>sphinx-build source docs (NOTE: the name docs can be changed if you wish)</li>
+        <li>sphinx-build source docs --fail-on-warning (optional flag, sometimes it works sometimes it does not. The warnings do not break the website build)</li> 
+    </ul>
+  </li>
+  <li>Open any html document located within your new folder using your web browser to preview your website</li>
+  <li>[Important] After you are done and want to push your changes to github you must ensure that you either delete the folder which was created when building this website, or add it to .gitignore if you plan on reusing it (see .gitignore file for examples)</li>
+</ol> 

source/developer/repo-automation.md

@@ -0,0 +1,34 @@
+# Website automation and github actions
+In order to automate some tedious processes we have created a new action on github called *Start docs update for website*, defined within the *. This github action allows the website code to be automatically updated with every push to main. 
+
+## Visual representation of github actions
+The image below contains a visual representation of how two of our repositories interact with one another. The simpler of the two, website repo, only contains one action which can be started by two triggers. Either manually or through a push to the main branch. Once either of these trigger the *Create/Update Website Action*, the website is then automatically created and pushed into a separate branch on the Website repository (gh-pages branch). The Core repository contains multiple different actions, however only the two relevant actions are shown. Publishing a new release on github triggers the *New PyPI Release Action*. Pushing into main triggers *Send Github API POST request*. In order for the illuminator package to be hosted on PyPI, we must first trigger *New PyPI Release Action* by creating a new github release on the Core repository. This PyPI illuminator package is what our website repository is referring to when automatically updating the documentation. The other action, *Send Github API POST request*, uses the secret token **WEBSITE_ACTION_TOKEN** to gain access to the Website Repo's actions, and triggers *Create/Update Website Action* as if it was manually triggered. This secret token is hosted within Core Repo's secrets, while it was created with the specific Actions read/write access rights exclusive to the website repository.
+
+<div align="center">
+	<img align="center" src="../_static/img/Illuminator_Repo_Actions.png" width="700">
+</div>
+
+
+## Action Token
+In order to trigger an action in a different repository an appropriate token must be created. This token is similar to the one created for access to github over a personal computer. 
+
+The steps necessary to create an appropriate token:
+1. Go to your account -> settings -> developer settings
+2. Personal access tokens -> Fine-grained tokens -> Generate New Token
+3. Give the token any name
+4. Change resource owner to illuminator-team
+5. Set an expiration date (the maximum is set by the illuminator-team)
+6. (Optional) Give a request message
+7. Set Repository Acces to Only select repositories
+8. Add Illuminator-team/website as your selected repository
+9. Under permissions add Actions and set to Read and Write
+10. Double check that there is 1 selected repository and 2 permissions (Actions and Metadata)
+11. Click Generate token and request access
+
+
+## Potential alterations/improvements
+- There is an action *Run Tests*, whose output is currently irrelevant to the website. It is possible to use *Run Tests* action as a prerequisite to *Send Github API POST request* action in order to double check if all the tests pass before updating the website.
+- Because the website uses the PyPI release of illuminator, if the code docstrings are altered and we wish for it to be visible on the illuminator website we must trigger *New PyPI Release Action* after we have created a push to main. Updating the website takes around 10 minutes, which gives plenty of time to create a new release, however it might be easier to simply change the trigger of *Send Github API POST request* from Push to Main to Publish new Github release.
+- The logic of using the Core Repo to trigger something on another repository could be reused for other repos as well. For example, for the Cluster Repo one could copy paste the action *Send Github API POST Request*, alter a few names and create a new secret token in a similar fashion to **WEBSITE_ACTION_TOKEN**. The only thing new would be the Action which is triggered in the Cluster Repo (for example: running tests)
+
+

source/index.rst

@@ -42,9 +42,11 @@ Illuminator builts on `Mosaik. <https://mosaik.offis.de/>`_ and supports both st
 
    developer/set-up.md
    developer/software-architecture.md
+   developer/repo-automation.md
    developer/developer-docstrings.md
    developer/testing-explained.md
    developer/writing-tests.md
+   developer/dev-website-contribute.md
 
 .. toctree::
    :maxdepth: 2