You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+61-71Lines changed: 61 additions & 71 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,8 @@
3
3
Follow these steps and note these guidelines to begin contributing:
4
4
5
5
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.
8
8
9
9
# Diagram of the infrastructure in use
10
10
@@ -14,56 +14,68 @@ Below are some diagrams to best explain the file structure of the website, the d
14
14
15
15
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.
16
16
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
26
17
```
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
+
27
31
28
32
## Development structure
29
33
30
34
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.
31
35
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/
49
36
```
37
+
Development Structure:
38
+
root/
39
+
├── _archive # old pages that should mostly be ignored
40
+
├── _posts/
41
+
│ ├── post1
42
+
│ └── post2
43
+
├── _layouts/
44
+
│ └── _includes/
45
+
├── _data/ # This is where yaml and json files live
46
+
│ ├── data_file1
47
+
│ └── data_file2
48
+
├── assets/ # static files that will be copied over
49
+
│ ├── css/
50
+
│ ├── images/
51
+
│ └── js/
52
+
├── pages/ # static pages represented in Render Engine under pages/
53
+
├── about.md # content pages
54
+
├── index.html
55
+
└── tests/
56
+
```
57
+
58
+
## How Pages are generated
59
+
60
+
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.
50
61
51
-
## How some information are generated
62
+
`app.py` is the instruction file for render engine.
52
63
53
64
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.
54
65
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
66
+
```python
67
+
@app.page
68
+
classAbout(Page):
69
+
template ="about.html"
70
+
data = yaml.safe_load(pathlib.Path("_data/leadership.yaml").read_text())
65
71
```
66
72
73
+
```
74
+
75
+
The `@app.page` tells Render Engine that we're building a single page vs a collection of pages.
76
+
77
+
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
78
+
67
79
# How to Contribute
68
80
69
81
## Fork the repository
@@ -107,56 +119,34 @@ The diagram below explains how information is generated for the about page, show
- 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`.
111
-
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:
- 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>:
- After installing the dependencies, it's time to run the application. We do this by running the command `uv run render-engine serve`
131
135
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:
136
+
- The server address shows `http://127.0.0.1:8000`.
> [!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:
135
139
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
-
140
+
139
141
140
142
### Testing Changes (create new tests as needed)
141
143
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.
144
+
- Run all tests in the test-suite with the command `uv run python -m pytest`:
- 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`:
0 commit comments