Skip to content

Commit 2d4d105

Browse files
kjaymillerkjaymiller
committed
update CONTRIBUTING.md
1 parent fdf898e commit 2d4d105

File tree

1 file changed

+64
-71
lines changed

1 file changed

+64
-71
lines changed

‎CONTRIBUTING.md‎

Lines changed: 64 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
Follow these steps and note these guidelines to begin contributing:
44

55
1. First step is to set up the local development environment.
6-
1. Bug fixes are always welcome. Start by reviewing the [list of bugs](https://github.com/BlackPythonDevs/blackpythondevs.github.io/issues).
7-
1. A good way to easily start contributing is to pick and work on a [good first issue](https://github.com/BlackPythonDevs/blackpythondevs.github.io/labels/good%20first%20issue). We try to make these issues as clear as possible and provide basic info on how the code should be changed, and if something is unclear feel free to ask for more information on the issue.
6+
2. Bug fixes are always welcome. Start by reviewing the [list of bugs](https://github.com/BlackPythonDevs/blackpythondevs.github.io/issues).
7+
3. A good way to easily start contributing is to pick and work on a [good first issue](https://github.com/BlackPythonDevs/blackpythondevs.github.io/labels/good%20first%20issue). We try to make these issues as clear as possible and provide basic info on how the code should be changed, and if something is unclear feel free to ask for more information on the issue.
88

99
# Diagram of the infrastructure in use
1010

@@ -14,56 +14,71 @@ Below are some diagrams to best explain the file structure of the website, the d
1414

1515
The diagram below illustrates the main navigation structure of BPD website, showing how the homepage `(Index)` connects to various sections, including the `Home`, `Blog`, `About Us`, `Events`, and `Community`. Each blog article, represented as `Article1` and `Article2`, is linked directly from the `Blog` section.
1616

17-
```mermaid
18-
flowchart TD
19-
Index --> Home
20-
Index --> Blog
21-
Blog --> Article1
22-
Blog --> Article2
23-
Index --> AboutUs
24-
Index --> Events
25-
Index --> Community
2617
```
18+
Website Structure:
19+
Index/
20+
├── Home
21+
├── Blog/
22+
│ ├── Article1
23+
│ └── Article2
24+
├── About Us
25+
├── Events
26+
├── Sponsored Events
27+
├── Community
28+
└── Sponsor Us
29+
```
30+
31+
TTT
2732

2833
## Development structure
2934

3035
The diagram below outlines the file structure of the development environment. The root node represents the main directory, containing essential files and folders like `_config.yml`, `_posts`, `_layouts`, `_includes`, `_data`, `_articles`, and `assets`. Each folder contains further organization of specific files. This will aid contributors in understanding how the project is organized and where different components are located.
3136

32-
```mermaid
33-
flowchart TD
34-
root --> _config.yml
35-
root --> _posts/
36-
root --> _layouts/
37-
root --> _includes/
38-
root --> _data/
39-
root --> _articles/
40-
root --> assets/
41-
root --> about.md
42-
root --> index.html
43-
root --> tests/
44-
_posts/ --> post1
45-
_posts/ --> post2
46-
assets/ --> css/
47-
assets/ --> images/
48-
assets/ --> js/
37+
```
38+
Development Structure:
39+
root/
40+
├── _archive # old pages that should mostly be ignored
41+
├── _posts/
42+
│ ├── post1
43+
│ └── post2
44+
├── _layouts/
45+
│ └── _includes/
46+
├── _data/ # This is where yaml and json files live
47+
│ ├── data_file1
48+
│ └── data_file2
49+
├── assets/ # static files that will be copied over
50+
│ ├── css/
51+
│ ├── images/
52+
│ └── js/
53+
├── pages/ # static pages represented in Render Engine und
54+
├── about.md # content pages
55+
├── index.html
56+
└── tests/
4957
```
5058

51-
## How some information are generated
59+
## How Pages are generated
60+
61+
The website uses render engine to read `app.py`. You can learn more about Render Engine on their [docs page](https://render-engine.readthedocs.io/en/stable/). The important locations to know.
62+
63+
`app.py` is the instruction file for render engine.
5264

5365
The diagram below explains how information is generated for the about page, showing how the `about.md`(source content) connects with other contents, templates and configuration files. The `about.md` file links to `_layouts/default.html` and `_includes/header.html` and `footer.html`, which define the page layout and thus generates a `about.html` this html file can be styled and scripted with files in the `assets/` folder. This diagram clarifies the rendering process and how different files work together to create the final output for the about page.
5466

55-
```mermaid
56-
flowchart TD
57-
about.md --> _layouts/default.html
58-
about.md --> _config.yml
59-
_layouts/default.html --> _includes/header.html
60-
_layouts/default.html --> _includes/footer.html
61-
_layouts/default.html --> about.html
62-
_config.yml --> about.html
63-
about.html --> assets/css/style.css
64-
about.html --> assets/js/script.js
67+
```python
68+
@app.page
69+
class About(Page):
70+
template = "about.html"
71+
data = yaml.safe_load(pathlib.Path("_data/leadership.yaml").read_text())
6572
```
6673

74+
```
75+
76+
```
77+
78+
The `@app.page` tells Render Engine that we're build a single page vs a collection of pages.
79+
80+
The `class About(Page):` tells us about the Page object. Attributes will pass information on render engine and the jinja template that will be loaded
81+
6782
# How to Contribute
6883

6984
## Fork the repository
@@ -107,56 +122,34 @@ The diagram below explains how information is generated for the about page, show
107122

108123
![Black Python Devs Codespace](/assets/images/blackpythondevs_codespace.png)
109124

110-
- Now that you have the code editor set up, you need to install the dependencies. To do this, you have to open the code editor's terminal and run the command `bundle install`.
125+
## Use UV
111126

112-
- The easiest way to open the terminal is to click on the 3 horizontal lines (also known as hamburger) at the top left of the code editor > Terminal > New Terminal:
127+
[uv](https://astral.sh/uv) is a Python package and project manager.
113128

114-
![Terminal starter](/assets/images/terminal_starter3.png)
129+
This project uses uv as it is currently the easiest way for developers with different levels of comfort of Python to quickly and safely get started.
115130

116-
- In the terminal run the command `bundle install`.
117-
118-
![Bundle install terminal](/assets/images/bundle_install_terminal.png)
119-
120-
- Afterwards, run the command `pip install -r requirements.txt` to install the python dev dependencies.
121-
122-
![Pip install terminal](/assets/images/pip_install_terminal.png)
131+
- Install the dependencies. In the terminal, at the project root, open the code editor's terminal and run the command `uv sync --extra dev`.
123132

124133
- Install the pre-commit hooks to automatically format the code before committing. Run the command `pre-commit install`:
125134

126135
![Pre-commit install terminal](/assets/images/pre-commit_install_terminal.png)
127136

128-
- After installing the dependencies, its time to run the application. We do this by running the command `bundle exec jekyll serve --detach` or run the default **Build Task** <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd>:
137+
- After installing the dependencies, its time to run the application. We do this by running the command `uv run render-engine serve`
129138

130-
![Jekyll serve terminal](/assets/images/jekyll_serve_terminal.png)
139+
- The server address shows `http://127.0.0.1:8000`.
131140

132-
- The server address shows `http://127.0.0.1:4000`. This is the address for any local computer so this server will be wrong since the application is running on a remote computer so we have to get the address of that computer. We can get the address by clicking on the Ports tab next to the Terminal:
141+
> [!NOTE] REMINDER: If using codespaces you will need to forward the port <kbd>Ctrl</kbd> + Click on the Forwarded Address assigned to Port 8000. This will open the running application in a new tab:
133142
134-
![Codespace ports](/assets/images/codespace_ports2.png)
135-
136-
- <kbd>Ctrl</kbd> + Click on the Forwarded Address assigned to Port 4000. This will open the running application in a new tab:
137-
138-
![Running page](/assets/images/running_page.png)
143+
![Running page](/assets/images/running_page.png)
139144

140145
### Testing Changes (create new tests as needed)
141146

142-
- To run the test suites for the codebase
143-
144-
- Ensure the site is running locally with `bundle exec jekyll serve --detach`. This will run the server in the background, and any content changes will immediately reflect on the site.
147+
- Run all tests in the test-suite with the command `uv run python -m pytest`:
145148

146-
![Jekyll serve terminal](/assets/images/jekyll_serve_terminal.png)
147-
148-
- If you need to restart the server, you can run `pkill -f jekyll` to stop the server and then run `bundle exec jekyll serve --detach` to start the server again.
149-
150-
- Run all tests in the test-suite with the command `python3 -m pytest`:
151-
152-
![Pytest terminal](/assets/images/pytest_run_terminal.png)
149+
![Pytest terminal](/assets/images/pytest_run_terminal.png)
153150

154151
### Pushing Changes
155152

156-
- Run `pre-commit run --all` to ensure your code is formatted and linted correctly before pushing your changes.
157-
158-
![Pre-commit run terminal](/assets/images/pre-commit_run_terminal.png)
159-
160153
- Run `git commit -m "<Your commit message>"` to commit your changes.
161154

162155
![Git commit terminal](/assets/images/git_commit_terminal.png)

0 commit comments

Comments
 (0)