Skip to content

Commit

Permalink
Merge pull request #3982 from raspberrypi/develop
Browse files Browse the repository at this point in the history 
Roll out latest improvements to production
  • Loading branch information
@nathan-contino
nathan-contino authored Dec 13, 2024
2 parents 4fbe29f + 858442d commit 63eaed0
Show file tree
Hide file tree
Showing 10 changed files with 204 additions and 206 deletions.
158 changes: 139 additions & 19 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,157 @@
# Contributing to Raspberry Pi Documentation
# Contributing to the Raspberry Pi Documentation

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.
The Raspberry Pi Documentation website is built from Asciidoc source using:

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

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

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.
## Contribute

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.
To contribute or update documentation:

**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.
1. Create a fork of this repository on your GitHub account.

**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.
1. Make changes in your fork. Start from the default `develop` branch.

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).
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!

**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.
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.

## Type of Content
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.

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.
1. After making any requested improvements to your PR, the maintainers will accept the PR and merge your changes into `develop`.

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.
1. When the maintainers next release the documentation by merging `develop` into `master`, your changes will go public on the production documentation site.

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

**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.
## Build

## Third-Party Services
### Install dependencies

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.
To build the Raspberry Pi documentation locally, you'll need Ruby, Python, and the Ninja build system.

## Licensing
#### Linux

Use `apt` to install the dependencies:

```console
$ sudo apt install -y ruby ruby-dev python3 python3-pip make ninja-build
```

Then, append the following lines to your `~/.bashrc` file (or equivalent shell configuration):

```bash
export GEM_HOME="$(ruby -e 'puts Gem.user_dir')"
export PATH="$PATH:$GEM_HOME/bin"
```

Close and re-launch your terminal window to use the new dependencies and configuration.

#### macOS

If you don't already have it, we recommend installing the [Homebrew](https://brew.sh/) package manager:

```console
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

Next, use Homebrew to install Ruby:

```console
$ brew install ruby
```

After installing Ruby, follow the instructions provided by Homebrew to make your new Ruby version easily accessible from the command line.

Then, use Homebrew to install the most recent version of Python:

```console
$ brew install python
```

Then, install the [Ninja build system](https://formulae.brew.sh/formula/ninja#default):

```console
$ brew install ninja
```

### Set up environment

Use the `gem` package manager to install the [Ruby bundler](https://bundler.io/), which this repository uses to manage Ruby dependencies:

```console
$ gem install bundler
```

Configure a Python virtual environment for this project:

```console
$ python -m venv .env
```

Activate the virtual environment:

```console
$ source .env/bin/activate
```

> [!TIP]
> 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.
In the virtual environment, install the [YAML module for Python 3](https://formulae.brew.sh/formula/pyyaml#default):

```console
$ pip3 install pyyaml
```

### Build HTML

> [!IMPORTANT]
> 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.
To build the documentation and start a local server to preview the built site, run the following command:

```console
$ make serve_html
```

You can access the virtual server at [http://127.0.0.1:4000/documentation/](http://127.0.0.1:4000/documentation/).

> [!TIP]
> 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.

### Build the Pico C SDK Doxygen documentation

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).

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 to build (tens of seconds) than the rest of the site.

Building the Pico C SDK Doxygen documentation requires the following additional package dependencies:

```console
$ sudo apt install -y cmake gcc-arm-none-eabi doxygen graphviz
```

Then, initialise the Git submodules used in the Pico C SDK section build:

```console
$ git submodule update --init
```

Run the following command to build the Pico C SDK section Asciidoc files from the Doxygen source:

```console
$ make build_doxygen_adoc
```

The next time you build the documentation site, you'll see the Pico C SDK section in your local preview.

> [!TIP]
> To delete and rebuild the generated files, run `make clean_doxygen_xml`, then re-run the build command.
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.
193 changes: 16 additions & 177 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,183 +1,22 @@
# Welcome to the Raspberry Pi Documentation
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/develop/pi_dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/develop/pi_light.svg">
<img alt="Raspberry Pi: computers and microcontrollers"
src="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/develop/pi_light.svg"
width="16%">
</picture>

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.
[Website][Raspberry Pi] | [Getting started] | [Documentation] | [Contribute]
</div>

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

## Building the Documentation

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.

### Checking out the Repository

Install `git` if you don't already have it, and check out the `documentation` repo as follows:
```
$ git clone https://github.com/raspberrypi/documentation.git
$ cd documentation
```

### Installing the Toolchain

#### On Linux

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.

You can install the necessary dependencies on Linux as follows:

```
$ sudo apt install -y ruby ruby-dev python3 python3-pip make ninja-build
```

then add these lines to the bottom of your `$HOME/.bashrc`:
```
export GEM_HOME="$(ruby -e 'puts Gem.user_dir')"
export PATH="$PATH:$GEM_HOME/bin"
```

and close and relaunch your Terminal window to have these new variables activated. Finally, run
```
$ gem install bundler
```
to install the latest version of the Ruby `bundle` command.

#### On macOS

If you don't already have it, install the [Homebrew](https://brew.sh/) package manager:

```
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

Next, install Ruby:

```
$ brew install ruby
```

And install the [Ruby bundler](https://bundler.io/):

```
$ gem install bundler
```

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`.

##### Set up Homebrew Version of Ruby

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:

```
$ echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
```

If you run macOS on an Intel-based Mac, replace `opt/homebrew` with `usr/local` in the above command.

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`.

Once you've made the changes to your shell configuration, open a new terminal instance and run the following command:

```
$ ruby --version
```

You should see output similar to the following:

```
ruby 3.2.2 (2023-03-30 revision e51014f9c0) [arm64-darwin22]
```

As long as you see a Ruby version greater than or equal to 3.2.2, you've succeeded.

##### Install Homebrew Dependencies

Next, use Homebrew to install the other dependencies.
Start with the latest version of Python:

```
$ brew install python@3
```

Then install the [Ninja build system](https://formulae.brew.sh/formula/ninja#default):

```
$ brew install ninja
```

Then install the [Gumbo HTML5 parser](https://formulae.brew.sh/formula/gumbo-parser#default):

```
$ brew install gumbo-parser
```

And finally, install the [YAML module for Python 3](https://formulae.brew.sh/formula/pyyaml#default):

```
$ pip3 install pyyaml
```

Now you've installed all of the dependencies you'll need from Homebrew.

### Install Scripting Dependencies

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):

```
$ bundle install
```

Then, run the following command to install the remaining required Python modules:

```
$ pip3 install --user -r requirements.txt
```

### Building the Documentation Site

After you've installed both the toolchain and scripting dependencies, you can build the documentation with the following command:

```
$ make
```

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/`.

You can also start a local server to view the built site:

```
$ make serve_html
```

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.

You can also use `make` to delete the `build/` and `documentation/html/` directories:

```
$ make clean
```

### Building with Doxygen

If you want to build the Pico C SDK Doxygen documentation alongside the main documentation site you will need to install some additional dependencies:

```
$ sudo apt install -y cmake gcc-arm-none-eabi doxygen graphviz
```

and then you can build the documentation with:

```
$ make build_doxygen_adoc
$ make
```

You clean up afterwards by using:

```
$ make clean_everything
```

which will revert the repository to a pristine state.
[Raspberry Pi]: https://www.raspberrypi.com/
[Getting Started]: https://www.raspberrypi.com/documentation/computers/getting-started.html
[Documentation]: https://www.raspberrypi.com/documentation/
[Contribute]: CONTRIBUTING.md

## Licence

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.
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.
4 changes: 2 additions & 2 deletions documentation/asciidoc/accessories/ai-camera/model-conversion.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The Model Compression Toolkit generates a quantised model in the following forma

To convert a model, first install the converter tools:

[tabs%sync]
[tabs]
======
TensorFlow::
+
Expand All @@ -58,7 +58,7 @@ If you need to install both packages, use two separate Python virtual environmen

Next, convert the model:

[tabs%sync]
[tabs]
======
TensorFlow::
+
Expand Down
Loading

0 comments on commit 63eaed0

Please sign in to comment.