Skip to content

Commit 83efe65

Browse files
nathan-continonathan-contino
committed
Update README and CONTRIBUTING to be more friendly to potential contributors
1 parent 7c2d655 commit 83efe65

File tree

10 files changed

+204
-206
lines changed

10 files changed

+204
-206
lines changed

‎CONTRIBUTING.md

Lines changed: 139 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,157 @@
1-
# Contributing to Raspberry Pi Documentation
1+
# Contributing to the Raspberry Pi Documentation
22

3-
The Raspberry Pi Documentation website is built from Asciidoc source using Asciidoctor and a Jekyll and Python toolchain. The website is automatically deployed to the raspberrypi.com site — pushed to production — using GitHub Actions when a push to the `master` branch occurs.
3+
The Raspberry Pi Documentation website is built from Asciidoc source using:
44

5-
Full instructions for building and running the documentation website locally can be found in the top-level [README.md](README.md) file.
5+
* [Asciidoctor](https://asciidoctor.org/)
6+
* [Jekyll](https://jekyllrb.com/)
7+
* [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)
8+
* Python
69

7-
## How to Contribute
10+
The website automatically deploys to [raspberrypi.com/documentation](raspberrypi.com/documentation) using GitHub Actions when new commits appear in the `master` branch.
811

9-
In order to contribute new or updated documentation, you must first create a GitHub account and fork the original repository to your own account. You can make changes, save them in your forked repository, then [make a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) against this repository. The pull request will appear [in the repository](https://github.com/raspberrypi/documentation/pulls) where it can be assessed by the maintainers, copy-edited, and if appropriate, merged with the official repository.
12+
## Contribute
1013

11-
Unless you are opening a pull request which will only make small corrections, for instance, to correct a typo, you are more likely to get traction for your changes if you [open an issue](https://github.com/raspberrypi/documentation/issues) first to discuss the proposed changes. Issues and Pull Requests older than 60 days will [automatically be marked as stale](https://github.com/actions/stale) and then closed 7 days later if there still hasn't been any further activity.
14+
To contribute or update documentation:
1215

13-
**NOTE:** The default [branch](https://github.com/raspberrypi/documentation/branches) of the repository is the `develop` branch, and this should be the branch you get by default when you initially checkout the repository. You should target any pull requests against the `develop` branch, pull requests against the `master` branch will automatically fail checks and not be accepted.
16+
1. Create a fork of this repository on your GitHub account.
1417

15-
**NOTE:** Issues and Pull Requests older than 60 days will [automatically be marked as stale](https://github.com/actions/stale) and then closed 7 days later if there still hasn't been any further activity.
18+
1. Make changes in your fork. Start from the default `develop` branch.
1619

17-
Before starting to write your contribution to the documentation, you should take a look at the [style guide](https://github.com/raspberrypi/style-guide/blob/master/style-guide.md).
20+
1. Read our [style guide](https://github.com/raspberrypi/style-guide/blob/master/style-guide.md) to ensure that your changes are consistent with the rest of our documentation. Since Raspberry Pi is a British company, be sure to include all of your extra `u`s and transfigure those `z`s (pronounced 'zeds') into `s`s!
1821

19-
**IMPORTANT**: Because the documentation makes use of the Asciidoc `include` statement, the `xref:` statements inside the documentation do not link back to the correct pages on Github, as Github does not support Asciidoc include functionality (see [#2005](https://github.com/raspberrypi/documentation/issues/2005)). However, these links work correctly when the HTML documentation is built and deployed. Please do not submit Pull Requests fixing link destinations unless you're sure that the link is broken [on the documentation site](https://www.raspberrypi.com/documentation/) itself.
22+
1. [Open a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) against this repository.
2023

21-
## Type of Content
24+
1. The maintainers will assess and copy-edit the PR. This can take anywhere from a few minutes to a few days, depending on the size of your PR, the time of year, and the availability of the maintainers.
2225

23-
We welcome contributions from the community, ranging from correcting small typos all the way through to adding entirely new sections to the documentation. However, going forward we're going to be fairly targeted about what sorts of content we add to the documentation. We are looking to keep the repository, and the documentation, focused on Raspberry Pi-specific things, rather than having generic Linux or computing content.
26+
1. After making any requested improvements to your PR, the maintainers will accept the PR and merge your changes into `develop`.
2427

25-
We are therefore deprecating the more generic documentation around using the Linux operating system, ahead of removing these sections entirely at some point in the future as part of a larger update to the documentation site. This move is happening as we feel these sort of more general topics are, ten years on from when the documentation was initially written, now much better covered elsewhere on the web.
28+
1. When the maintainers next release the documentation by merging `develop` into `master`, your changes will go public on the production documentation site.
2629

27-
As such, we're not accepting PRs against these sections unless they're correcting errors.
30+
Alternatively, [open an issue](https://github.com/raspberrypi/documentation/issues) to discuss proposed changes.
2831

29-
**NOTE:** We are willing to consider toolchain-related contributions, but changes to the toolchain may have knock-on effects in other places, so it is possible that apparently benign pull requests that make toolchain changes could be refused for fairly opaque reasons.
32+
## Build
3033

31-
## Third-Party Services
34+
### Install dependencies
3235

33-
In general, we will not accept content that is specific to an individual third-party service or product. We will also not embed, or add links, to YouTube videos showing tutorials on how to configure your Raspberry Pi.
36+
To build the Raspberry Pi documentation locally, you'll need Ruby, Python, and the Ninja build system.
3437

35-
## Licensing
38+
#### Linux
39+
40+
Use `apt` to install the dependencies:
41+
42+
```console
43+
$ sudo apt install -y ruby ruby-dev python3 python3-pip make ninja-build
44+
```
45+
46+
Then, append the following lines to your `~/.bashrc` file (or equivalent shell configuration):
47+
48+
```bash
49+
export GEM_HOME="$(ruby -e 'puts Gem.user_dir')"
50+
export PATH="$PATH:$GEM_HOME/bin"
51+
```
52+
53+
Close and re-launch your terminal window to use the new dependencies and configuration.
54+
55+
#### macOS
56+
57+
If you don't already have it, we recommend installing the [Homebrew](https://brew.sh/) package manager:
58+
59+
```console
60+
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
61+
```
62+
63+
Next, use Homebrew to install Ruby:
64+
65+
```console
66+
$ brew install ruby
67+
```
68+
69+
After installing Ruby, follow the instructions provided by Homebrew to make your new Ruby version easily accessible from the command line.
70+
71+
Then, use Homebrew to install the most recent version of Python:
72+
73+
```console
74+
$ brew install python
75+
```
76+
77+
Then, install the [Ninja build system](https://formulae.brew.sh/formula/ninja#default):
78+
79+
```console
80+
$ brew install ninja
81+
```
82+
83+
### Set up environment
84+
85+
Use the `gem` package manager to install the [Ruby bundler](https://bundler.io/), which this repository uses to manage Ruby dependencies:
86+
87+
```console
88+
$ gem install bundler
89+
```
90+
91+
Configure a Python virtual environment for this project:
92+
93+
```console
94+
$ python -m venv .env
95+
```
96+
97+
Activate the virtual environment:
98+
99+
```console
100+
$ source .env/bin/activate
101+
```
102+
103+
> [!TIP]
104+
> When you're using a virtual environment, you should see a `(.venv)` prefix at the start of your terminal prompt. At any time, run the `deactivate` command to exit the virtual environment.
105+
106+
In the virtual environment, install the [YAML module for Python 3](https://formulae.brew.sh/formula/pyyaml#default):
107+
108+
```console
109+
$ pip3 install pyyaml
110+
```
111+
112+
### Build HTML
113+
114+
> [!IMPORTANT]
115+
> If you configured a Python virtual environment as recommended in the previous step, **always** run `source .env/bin/activate` before building. You must activate the virtual environment to access to all of the Python dependencies installed in that virtual environment.
116+
117+
To build the documentation and start a local server to preview the built site, run the following command:
118+
119+
```console
120+
$ make serve_html
121+
```
122+
123+
You can access the virtual server at http://127.0.0.1:4000/documentation/[http://127.0.0.1:4000/documentation/].
124+
125+
> [!TIP]
126+
> To delete and rebuild the documentation site, run `make clean`, then re-run the build command. You'll need to do this every time you add or remove an Asciidoc, image, or video file.
127+
128+
129+
### Build the Pico C SDK Doxygen documentation
130+
131+
The Raspberry Pi documentation site includes a section of generated Asciidoc that we build from the [Doxygen Pico SDK documentation](https://github.com/raspberrypi/pico-sdk).
132+
133+
We use the tooling in this repository and [doxygentoasciidoc](https://github.com/raspberrypi/doxygentoasciidoc) to generate that documentation section. By default, local documentation builds don't include this section because it takes a bit longer (tens of seconds) than the rest of the site.
134+
135+
Building the Pico C SDK Doxygen documentation requires the following additional package dependencies:
136+
137+
```console
138+
$ sudo apt install -y cmake gcc-arm-none-eabi doxygen graphviz
139+
```
140+
141+
Then, initialise the Git submodules used in the Pico C SDK section build:
142+
143+
```console
144+
$ git submodule update --init
145+
```
146+
147+
Run the following command to build the Pico C SDK section Asciidoc files from the Doxygen source:
148+
149+
```console
150+
$ make build_doxygen_adoc
151+
```
152+
153+
The next time you build the documentation site, you'll see the Pico C SDK section in your local preview.
154+
155+
> [!TIP]
156+
> To delete and rebuild the generated files, run `make clean_doxygen_xml`, then re-run the build command.
36157
37-
The documentation is under a [Creative Commons Attribution-Sharealike](https://creativecommons.org/licenses/by-sa/4.0/) (CC BY-SA 4.0) licence. By contributing content to this repository, you are agreeing to place your contributions under this licence.

‎README.md

Lines changed: 16 additions & 177 deletions
Original file line numberDiff line numberDiff line change
@@ -1,183 +1,22 @@
1-
# Welcome to the Raspberry Pi Documentation
1+
<div align="center">
2+
<picture>
3+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/images/pi_dark.svg">
4+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/images/pi_light.svg">
5+
<img alt="Raspberry Pi: computers and microcontrollers"
6+
src="https://raw.githubusercontent.com/raspberrypi/documentation/images/pi_light.svg"
7+
width="50%">
8+
</picture>
29

3-
This repository contains the Asciidoc source and the toolchain to build the [Raspberry Pi Documentation](https://www.raspberrypi.com/documentation/). For details of how to contribute to the documentation see the [CONTRIBUTING.md](CONTRIBUTING.md) file.
10+
[Website][Raspberry Pi] | [Getting started] | [Documentation] | [Contribute]
11+
</div>
412

5-
**NOTE:** This repository has undergone some recent changes. See our [blog post](https://www.raspberrypi.com/blog/bring-on-the-documentation/) for more details.
13+
This repository contains the source and tools used to build the [Raspberry Pi Documentation](https://www.raspberrypi.com/documentation/).
614

7-
## Building the Documentation
8-
9-
Instructions on how to checkout the `documentation` repo, and then install the toolchain needed to convert from Asciidoc to HTML and build the documentation site.
10-
11-
### Checking out the Repository
12-
13-
Install `git` if you don't already have it, and check out the `documentation` repo as follows:
14-
```
15-
$ git clone https://github.com/raspberrypi/documentation.git
16-
$ cd documentation
17-
```
18-
19-
### Installing the Toolchain
20-
21-
#### On Linux
22-
23-
This works on both regular Debian or Ubuntu Linux — and has been tested in a minimal Docker container — and also under Raspberry Pi OS if you are working from a Raspberry Pi.
24-
25-
You can install the necessary dependencies on Linux as follows:
26-
27-
```
28-
$ sudo apt install -y ruby ruby-dev python3 python3-pip make ninja-build
29-
```
30-
31-
then add these lines to the bottom of your `$HOME/.bashrc`:
32-
```
33-
export GEM_HOME="$(ruby -e 'puts Gem.user_dir')"
34-
export PATH="$PATH:$GEM_HOME/bin"
35-
```
36-
37-
and close and relaunch your Terminal window to have these new variables activated. Finally, run
38-
```
39-
$ gem install bundler
40-
```
41-
to install the latest version of the Ruby `bundle` command.
42-
43-
#### On macOS
44-
45-
If you don't already have it, install the [Homebrew](https://brew.sh/) package manager:
46-
47-
```
48-
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
49-
```
50-
51-
Next, install Ruby:
52-
53-
```
54-
$ brew install ruby
55-
```
56-
57-
And install the [Ruby bundler](https://bundler.io/):
58-
59-
```
60-
$ gem install bundler
61-
```
62-
63-
If you're using a system version of Python 3.12, you may also need to run the Python 3.12 certificate-installation script. Find the Python3.12 folder on your machine, and run `Install Certificates.command`.
64-
65-
##### Set up Homebrew Version of Ruby
66-
67-
Because macOS provides its own version of Ruby, Homebrew doesn't automatically set up symlinks to access the version you just installed with the `ruby` command. But after a successful install, Homebrew outputs the commands you'll need to run to set up the symlink yourself. If you use the default macOS `zsh` shell on Apple Silicon, you can set up the symlink with the following command:
68-
69-
```
70-
$ echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
71-
```
72-
73-
If you run macOS on an Intel-based Mac, replace `opt/homebrew` with `usr/local` in the above command.
74-
75-
If you run a shell other than the default, check which config file to modify for the command. For instance, `bash` uses `~/.bashrc` or `~/.bash_profile`.
76-
77-
Once you've made the changes to your shell configuration, open a new terminal instance and run the following command:
78-
79-
```
80-
$ ruby --version
81-
```
82-
83-
You should see output similar to the following:
84-
85-
```
86-
ruby 3.2.2 (2023-03-30 revision e51014f9c0) [arm64-darwin22]
87-
```
88-
89-
As long as you see a Ruby version greater than or equal to 3.2.2, you've succeeded.
90-
91-
##### Install Homebrew Dependencies
92-
93-
Next, use Homebrew to install the other dependencies.
94-
Start with the latest version of Python:
95-
96-
```
97-
$ brew install python@3
98-
```
99-
100-
Then install the [Ninja build system](https://formulae.brew.sh/formula/ninja#default):
101-
102-
```
103-
$ brew install ninja
104-
```
105-
106-
Then install the [Gumbo HTML5 parser](https://formulae.brew.sh/formula/gumbo-parser#default):
107-
108-
```
109-
$ brew install gumbo-parser
110-
```
111-
112-
And finally, install the [YAML module for Python 3](https://formulae.brew.sh/formula/pyyaml#default):
113-
114-
```
115-
$ pip3 install pyyaml
116-
```
117-
118-
Now you've installed all of the dependencies you'll need from Homebrew.
119-
120-
### Install Scripting Dependencies
121-
122-
After installing the toolchain, install the required Ruby gems and Python modules. Make sure you're in the top-level directory of this repository (the one containing `Gemfile.lock` and `requirements.txt`), and run the following command to install the Ruby gems (this may take several minutes):
123-
124-
```
125-
$ bundle install
126-
```
127-
128-
Then, run the following command to install the remaining required Python modules:
129-
130-
```
131-
$ pip3 install --user -r requirements.txt
132-
```
133-
134-
### Building the Documentation Site
135-
136-
After you've installed both the toolchain and scripting dependencies, you can build the documentation with the following command:
137-
138-
```
139-
$ make
140-
```
141-
142-
This automatically uses [Ninja build](https://ninja-build.org/) to convert the source files in `documentation/asciidoc/` to a suitable intermediate structure in `build/jekyll/` and then uses [Jekyll AsciiDoc](https://github.com/asciidoctor/jekyll-asciidoc) to convert the files in `build/jekyll/` to the final output HTML files in `documentation/html/`.
143-
144-
You can also start a local server to view the built site:
145-
146-
```
147-
$ make serve_html
148-
```
149-
150-
As the local server launches, the local URL will be printed in the terminal -- open this URL in a browser to see the locally-built site.
151-
152-
You can also use `make` to delete the `build/` and `documentation/html/` directories:
153-
154-
```
155-
$ make clean
156-
```
157-
158-
### Building with Doxygen
159-
160-
If you want to build the Pico C SDK Doxygen documentation alongside the main documentation site you will need to install some additional dependencies:
161-
162-
```
163-
$ sudo apt install -y cmake gcc-arm-none-eabi doxygen graphviz
164-
```
165-
166-
and then you can build the documentation with:
167-
168-
```
169-
$ make build_doxygen_adoc
170-
$ make
171-
```
172-
173-
You clean up afterwards by using:
174-
175-
```
176-
$ make clean_everything
177-
```
178-
179-
which will revert the repository to a pristine state.
15+
[Raspberry Pi]: https://www.raspberrypi.com/
16+
[Getting Started]: https://www.raspberrypi.com/documentation/computers/getting-started.html
17+
[Documentation]: https://www.raspberrypi.com/documentation/
18+
[Contribute]: CONTRIBUTING.md
18019

18120
## Licence
18221

183-
The Raspberry Pi [documentation](./documentation/) is [licensed](https://github.com/raspberrypi/documentation/blob/develop/LICENSE.md) under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA). While the toolchain source code — which is everything outside of the top-level `documentation/` subdirectory — is Copyright © 2021 Raspberry Pi Ltd and licensed under the [BSD 3-Clause](https://opensource.org/licenses/BSD-3-Clause) licence.
22+
The Raspberry Pi documentation is [licensed](https://github.com/raspberrypi/documentation/blob/develop/LICENSE.md) under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA). Documentation tools (everything outside of the `documentation/` subdirectory) are licensed under the [BSD 3-Clause](https://opensource.org/licenses/BSD-3-Clause) licence.

‎documentation/asciidoc/accessories/ai-camera/model-conversion.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The Model Compression Toolkit generates a quantised model in the following forma
3535

3636
To convert a model, first install the converter tools:
3737

38-
[tabs%sync]
38+
[tabs]
3939
======
4040
TensorFlow::
4141
+
@@ -58,7 +58,7 @@ If you need to install both packages, use two separate Python virtual environmen
5858

5959
Next, convert the model:
6060

61-
[tabs%sync]
61+
[tabs]
6262
======
6363
TensorFlow::
6464
+

0 commit comments

Comments
 (0)