Skip to content

Commit e147fe7

Browse files
authored
Merge pull request #155 from st0012/document-documentation-generation-pipeline
Add CONTRIBUTING.md to outline the documentation generation pipeline
2 parents d1aaca7 + 2cad8ca commit e147fe7

File tree

1 file changed

+22
-0
lines changed

1 file changed

+22
-0
lines changed

CONTRIBUTING.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Contributing
2+
3+
## How docs.ruby-lang.org/en Works
4+
5+
### Overview
6+
7+
The English Ruby documentation is automatically generated and updated through a pipeline involving GitHub Actions, AWS S3, and systemd services. Here's how it all comes together:
8+
9+
1. **Documentation Generation and Upload**
10+
11+
- A scheduled [GitHub Action](https://github.com/ruby/actions/blob/master/.github/workflows/docs.yml) generates the documentation for all [actively maintained Ruby versions](https://www.ruby-lang.org/en/downloads/branches/) plus the master branch. Each documentation set is generated using the version of RDoc bundled with that specific Ruby version.
12+
- *Example:* For [Ruby 3.3](https://docs.ruby-lang.org/en/3.3/), the documentation is generated with RDoc 6.6.3.1.
13+
- The generated docs are uploaded as `ruby-docs-en-<version>.tar.xz` to the `ftp.r-l.o/pub/ruby/doc/` S3 bucket.
14+
- You can find these uploads at [cache.ruby-lang.org/pub/ruby/doc/](https://cache.ruby.org/pub/ruby/doc/), which is powered by [cache.r-l.o](https://github.com/ruby/cache.r-l.o).
15+
16+
2. **Website Update**
17+
18+
- On the server running this application, the `update-docs-en.timer` systemd timer triggers the `rdoc-static-all` service at scheduled intervals.
19+
- Timer definition: [update-docs-en.timer](https://github.com/ruby/docs.ruby-lang.org/blob/master/provision/systemd/update-docs-en.timer)
20+
- Service definition: [rdoc-static-all.service](https://github.com/ruby/docs.ruby-lang.org/blob/master/provision/systemd/rdoc-static-all.service)
21+
- The `rdoc-static-all` service runs the [rdoc-static-all](https://github.com/ruby/docs.ruby-lang.org/blob/master/system/rdoc-static-all) script.
22+
- This script downloads the latest documentation from S3 and updates the website accordingly.

0 commit comments

Comments
 (0)