Skip to content

Commit 33c99a0

Browse files
geekaugeekau
committed
document prep
1 parent f8258f4 commit 33c99a0

14 files changed

+2581
-6
lines changed

‎README.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
# mediastack.guide
22
Content for MediaStack.Guide Website
3+
4+
Goto: [https://MediaStack.Guide](https://MediaStack.Guide)

‎docs/contributing.md

+177
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Contributing to https://MediaStack.Guide
2+
3+
Anyone can easily join and contribute to the https://MediaStack.Guide GitHub repo, to improve the overall documentation / website by following these steps.
4+
5+
First, you will need an active GitHub.com account if you are looking to push changes / updates back to the https://MediaStack.Guide repo on GitHub
6+
7+
Setting up your environment to run MkDocs for Development / Contribution to https://MediaStack.Guide
8+
9+
**Download and Install Microsoft Visual Studio Code**
10+
- https://code.visualstudio.com/download
11+
12+
**Download and Install Git for Windows**
13+
- https://git-scm.com/download/win
14+
15+
**Download and Install Python**
16+
- https://www.python.org/downloads
17+
18+
**Download and Install Miniconda**
19+
- https://docs.conda.io/en/latest/miniconda.html
20+
21+
**Goto Visual Studio Code Extentions (Ctrl+Shift+X) and Install:**
22+
- Python (by Microsoft)                            Or at: https://marketplace.visualstudio.com/items?itemName=ms-python.python
23+
- Python Environment Manager               Or at: https://marketplace.visualstudio.com/items?itemName=donjayamanne.python-environment-manager
24+
- Start git-bash                                         Or at: https://marketplace.visualstudio.com/items?itemName=McCarter.start-git-bash
25+
- GitHub Repositories                               Or at: https://marketplace.visualstudio.com/items?itemName=GitHub.remotehub
26+
- GitHub Pull Requests and Issues           Or at: https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github
27+
- YAML                                                     Or at: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
28+
- shell-format https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format
29+
30+
**Optional Visual Studio Code Extentions:**
31+
- Azure Repos (Optional for TFVC)           Or at: https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-repos
32+
- WSL (optional) - If using WSL                Or at: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl
33+
- WSL Recommender - If using WSL         Or at: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl-recommender
34+
35+
**Test all of the programs are working correctly:**
36+
- Open Windows Start Menu, you should be able to see:
37+
- Anaconda Prompt (Miniconda3)
38+
- Git Bash
39+
- Python 3.11 (64-bit)
40+
41+
- Start "Git Bash" and run these commands to see if they're in the environment path (may need a reboot if this is the first time running them)
42+
- Execute "conda"
43+
- Execute "pip"
44+
- Execute "py --version"
45+
46+
>The above tests should confirm you have the correct packages installed and the paths are working, in order to create the Conda environment needed to host the MkDocs files while editing / contributing on your local system.
47+
48+
49+
Start "Git Bash" from the Windows Start Menu, and create a folder to replicate any GitHub repos to.. i.e. "C:\GitHub"
50+
51+
```
52+
mkdir C:\GitHub
53+
cd C:\GitHub
54+
git clone https://github.com/geekau/mediastack.guide.git
55+
cd mediastack.guide
56+
code .
57+
```
58+
59+
Visual Studio will now open and ask you to trust the files you have pull from GitHub into the "C:\GitHub\mediastack.guide" folder - Select Yes to trust the folder.
60+
61+
62+
**Select Python Intepreter**
63+
64+
In Visual Studio Code opening the Command Palette (Ctrl+Shift+P), start typing "Python: Select Interpreter" - Press Enter
65+
66+
Select: "Python 3.9... ('base') C:\ProgramData\Miniconda3\python.exe **Conda**"
67+
68+
**Select Terminal Intepreter**
69+
70+
In Visual Studio Code opening the Command Palette (Ctrl+Shift+P), start typing "Terminal: Select Default Profile" - Press Enter and select: "Git Bash"
71+
72+
From the top menu, select "Terminal" --> "New Terminal" (Ctrl+Shift+`), the new terminal should now be "Git Bash".
73+
74+
**Setup Python environment to support the downloaded MediaStack.Guide files**
75+
76+
From the Git Bash terminal, type ls -la, you should be inside the "C:\GitHub\mediastack.guide" folder, and be able to see the following files:
77+
78+
- init_setup.sh - Script to built a local Python environment on your system for development / testing
79+
- requirements.txt - Includes the files needed as part of the local environment (MkDocs, Material for MkDocs, Awesome Pages for MkDocs etc..)
80+
- runtime.txt - Sets the Conda sets the Python version to 3.7, so all developers contributing on MediaStack.Guide repo are all using the same version
81+
82+
As this is the first time using the Git Bash terminal, you may need to initialiase it with the following command, then closing / restarting the terminal window:
83+
84+
```
85+
conda init bash
86+
```
87+
88+
If you are in the correct folder and can see all of these files, then you can execute the following command in the Git Bash terminal to build your environment:
89+
90+
```
91+
bash init_setup.sh
92+
```
93+
94+
>This will take a few minutes to build your local environment, depending on your Internet speed.
95+
96+
**Activate the virtual environment for the mediastack.guide project**
97+
98+
In order to run any of the commands / scripts which have now been set up in the "ENV" environment, you need to activiate the environment with the following command:
99+
100+
```
101+
conda activiate ./env
102+
```
103+
104+
Now the environment has been activated, you can call commands from that environment, to help you develop and test using the environment which is now standardised for all contributing developers.
105+
106+
Type the following command to run a local webserver on port 8888, which will serve all of the MkDocs files from your working copy
107+
108+
```
109+
mkdocs serve
110+
```
111+
112+
You should see the following output:
113+
```
114+
$ mkdocs serve
115+
INFO - Building documentation...
116+
INFO - Cleaning site directory
117+
INFO - Documentation built in 0.02 seconds
118+
INFO - [12:00:00] Watching paths for changes: 'docs', 'mkdocs.yml'
119+
INFO - [12:00:00] Serving on http://127.0.0.1:8000/
120+
```
121+
122+
You should be able to open a web browser on http://127.0.0.1:8000/ and see all of the files you have pulled down from the repository, and they will automatically update on the local web server as you make any file saves to your local copy of the repository.
123+
124+
>Press CTRL+C to exit the mkdocs server
125+
126+
**Project development branches on GitHub**
127+
128+
If you make changes to your local copies of the files and want to "push" them back up to the GitHub repository, there are currently three branches being used for development / release:
129+
130+
- commits: This is the branch that all community contributions should be pushed to.
131+
- preview: The review committee will pull changes which have been uploaded to the commit branch, into the preview branch, in order to stage any updates, prior to going into the main branch.
132+
- main: This is the "main" / production branch, that is linked to the https://MediaStack.Guide web server, and all updates will be reviewed rigoursly prior to merging from the preview branch.
133+
134+
135+
**Viewing development / production branches on the website**
136+
137+
- main: https://MediaStack.Guide
138+
- preview: https://
139+
- commits: https://
140+
141+
142+
**Open Markdown preview window in the side window**
143+
144+
In Visual Studio Code opening the Command Palette (Ctrl+Shift+P), start typing "Markdown: Open Preview to the Side" - Press Enter
145+
146+
147+
**Environments are not working**
148+
149+
If the commands for conda, pip, bash, py etc... are not working, you may need to add these folders to your "PATH" system environment variable, and restart your computer:
150+
```
151+
C:\Program Files\Python311\
152+
C:\Program Files\Python311\Scripts\
153+
C:\ProgramData\Miniconda3
154+
C:\ProgramData\Miniconda3\Scripts
155+
C:\ProgramData\Miniconda3\shell\condabin
156+
```
157+
158+
**Additional guidance on how to set up Python and Conda with Visual Studio Code**
159+
160+
Setup Anaconda (Python) to Work With Visual Studio Code on Windows:
161+
- https://opensourceoptions.com/blog/setup-anaconda-python-to-work-with-visual-studio-code-on-windows/
162+
163+
Python for Visual Studio Code:
164+
- https://docs.anaconda.com/anaconda/user-guide/tasks/integration/python-vsc/
165+
166+
167+
**Some guidance on how to work collaboratively with others, using Visual Studio Code and GitHub**
168+
169+
Good reading on how to Collaborate on GitHub using Visual Studio Code
170+
- https://code.visualstudio.com/docs/sourcecontrol/overview
171+
- https://code.visualstudio.com/docs/sourcecontrol/github
172+
- https://code.visualstudio.com/docs/sourcecontrol/faq
173+
174+
signing commits
175+
https://ona.io/home/signing-git-commits-using-your-gpg-key/
176+
177+
git config --global commit.gpgsign true

‎docs/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Welcome to MkDocs
1+
# Welcome to MediaStack.Guide
22

33
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
44

0 commit comments

Comments
 (0)