rsyslog/rsyslog
1
0
Fork 0
mirror of https://github.com/rsyslog/rsyslog.git synced 2026-06-19 21:02:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

update developer doc to point to new rsyslog-doc location

Browse Source
This commit is contained in:
Rainer Gerhards 2025-06-15 08:10:21 +02:00
parent 919d409e0a
commit 9bfbdf22b3
No known key found for this signature in database
GPG Key ID: 0CB6B2A8BE80B499
2 changed files with 112 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
AGENTS.md
View File

@ -10,7 +10,7 @@ This file defines guidelines and instructions for AI assistants (e.g., Codex, Gi
- **Build System**: autotools (`autogen.sh`, `configure`, `make`)
- **Modules**: Dynamically loaded from `modules/`
- **Contributions**: Additional modules and features are placed in `contrib/`, which contains community-contributed plugins not actively maintained by the core rsyslog team. These are retained in `contrib/` even if adopted later, to avoid disruptions in dependent software.
- **Documentation**: Maintained in a separate repository ([rsyslog-doc](https://github.com/rsyslog/rsyslog-doc))
- **Documentation**: Maintained in the doc/ subdirectory
- **Child Projects**:
- [`rsyslog-docker`](https://github.com/rsyslog/rsyslog-docker): Provides prebuilt container environments for development and CI
- **Side Libraries** (each in its own repo within the rsyslog GitHub org):

225
doc/README.md
View File

@ -1,174 +1,171 @@
# rsyslog-docs
## Documentation for the rsyslog project
# Documentation for the rsyslog project
Documentation for rsyslog is generated with the (Python) Sphinx documentation
processor. Documentation for the `rsyslog-doc` project itself is provided
processor. Documentation for the rsyslog project itself is provided
by this README and other documentation linked from this file.
## Learning the doc tools
If you are new to rst and Sphinx, see the Sphinx documentation to get started:
If you're new to rst and Sphinx, see the Sphinx documentation to get started:
http://www.sphinx-doc.org/en/stable/contents.html
## Contributed Software/Content
In the repo you will find a `contrib` directory.
In the repo, you'll find a `doc/contrib` directory. This directory contains
content contributed by community members. All content in the `rsyslog`
repository, including contributions, is subject to review processes for quality
and adherence to project standards.
Although content in this directory is part of the official `rsyslog-doc`
repo, the status is different. While other content in this repo is fully
supported by the dev team, content in the `contrib` directory is supported
primarily by the contributor who provided it.
Content may range from small one-off scripts to tools for automating builds
of the docs. See the [contrib README](contrib/README.md) for details.
If you have new things to add to this area, please follow the directions
on this page for contributing to the docs and submit your changes as
a new Pull Request.
---
## Dev Team resources
In addition to the directions here, there is also a separate
[BUILDS_README.md](BUILDS_README.md) file for use by `rsyslog-doc` team
members. This doc is used as a quick reference for those who regularly
In addition to the directions here, there's also a separate
[BUILDS_README.md](doc/BUILDS_README.md) file for use by `rsyslog` team
members. This doc serves as a quick reference for those who regularly
provide dev and official release builds of the documentation.
---
## Contributing to the docs
1. Login with a GitHub account
1. Fork the official https://github.com/rsyslog/rsyslog-doc repo
1. Create a new branch off of the latest `master` branch
1. Make your changes
1. Commit to the new branch in your fork
1. Submit a Pull Request (PR) for review
(https://github.com/rsyslog/rsyslog-doc/pulls)
1. Stop making any changes to your new branch now that you have submitted a
Pull Request for review. Instead, create a new branch from your `master`
branch while you wait for feedback from the doc team.
1. A member of the team will review and offer feedback on your work. After
feedback has been given and you have made all necessary changes, your
PR will be accepted and merged into the official `master` branch.
1. At this point, delete your branch that you submitted the PR from and start
a new one for the next round of work.
1. Log in with a GitHub account.
2. Fork the official https://github.com/rsyslog/rsyslog repo.
3. Create a new branch off of the latest `master` branch.
4. Make your changes in the **`doc/`** subfolder.
5. Commit to the new branch in your fork.
6. Submit a Pull Request (PR) for review
(https://github.com/rsyslog/rsyslog/pulls). **Note that PRs will be automatically AI reviewed.**
7. Stop making any changes to your new branch now that you've submitted a
Pull Request for review. Instead, create a new branch from your `master`
branch while you wait for feedback from the doc team.
8. A team member will review and offer feedback on your work. After
feedback has been given and you've made all necessary changes, your
PR will be accepted and merged into the official `master` branch.
9. At this point, delete the branch you submitted the PR from and start
a new one for your next round of work.
For small changes, the work can be done entirely through the GitHub web
For small changes, you can do all the work through the GitHub web
interface. For larger changes, some familiarity with Git is useful, though
some editors such as Atom or Visual Studio Code make interfacing with Git
editors like Atom or Visual Studio Code make interfacing with Git
easier for newcomers.
Before you begin your work, you are encouraged to review the existing PRs and
open issues so that you can coordinate your work with other contributors.
Before you begin your work, we encourage you to review existing PRs and
open issues so you can coordinate your work with other contributors.
Please reach out if you have any questions as you work through making your
changes.
Tip: If you would like something less complex to get started with, please see
**Tip:** If you'd like something less complex to get started with, please see
issues tagged with
[good first issue](https://github.com/rsyslog/rsyslog-doc/labels/good%20first%20issue)
or [help wanted](https://github.com/rsyslog/rsyslog-doc/labels/help%20wanted)
[good first issue](https://github.com/rsyslog/rsyslog/labels/good%20first%20issue)
or [help wanted](https://github.com/rsyslog/rsyslog/labels/help%20wanted).
---
## Requesting feedback/help
While working on changes to the docs, you are encouraged to seek input from
other members of the community. This can be done via the mailing list, here
on GitHub by submitting a new issue or (experimentally) by [posting a question
While working on changes to the docs, we encourage you to seek input from
other members of the community. You can do this via the mailing list, here
on GitHub by submitting a new issue, or (experimentally) by [posting a question
to Stack Exchange](https://serverfault.com/questions/ask?tags=rsyslog).
- Mailing list: http://lists.adiscon.net/mailman/listinfo/rsyslog
- Stack Exchange (experimental)
- [Ask a question](https://serverfault.com/questions/ask?tags=rsyslog)
- [View existing questions](https://stackexchange.com/filters/327462/rsyslog)
- Mailing list: http://lists.adiscon.net/mailman/listinfo/rsyslog
- Stack Exchange (experimental)
- [Ask a question](https://serverfault.com/questions/ask?tags=rsyslog)
- [View existing questions](https://stackexchange.com/filters/327462/rsyslog)
---
## Building the documentation
These directions assume default installs of Python for Windows and Linux.
Because the [Sphinx project recommends using Python 2.7](http://www.sphinx-doc.org/en/stable/install.html),
that is what is shown here.
Since the [Sphinx project recommends using Python 2.7](http://www.sphinx-doc.org/en/stable/install.html),
that's what we'll show here.
### Assumptions
- You wish to install the `pip` Python package as a standard user, which places
installed packages into that user's home directory. Remove the `--user`
flag if you wish to install system-wide for all users instead.
- You want to install the `pip` Python package as a standard user, which places
installed packages into that user's home directory. Remove the `--user`
flag if you want to install system-wide for all users instead.
- You wish to use a virtual environment to install Sphinx and its dependencies
into a dedicated environment instead of installing alongside packages that
were installed system-wide or to the user's home directory with the `--user`
flag. If you wish to install the `sphinx` package and all dependent packages
for all users of the system, then you will need to run the package
installation commands as an elevated user account (e.g., `sudo`, `su` or
with administrator rights on a Windows system).
- You want to use a virtual environment to install Sphinx and its dependencies
into a dedicated environment instead of installing alongside packages that
were installed system-wide or to the user's home directory with the `--user`
flag. If you want to install the `sphinx` package and all dependent packages
for all users of the system, then you'll need to run the package
installation commands as an elevated user account (e.g., `sudo`, `su`, or
with administrator rights on a Windows system).
- You are running through these steps for the first time. Leave out the steps
involving installation of packages and applications if generating an updated
copy of the documentation.
- You're running through these steps for the first time. Skip the steps
involving installation of packages and applications if you're just generating an updated
copy of the documentation.
### Prep environment
The first part of the process is a little different depending on your OS. The
later steps are identical, so those steps have been covered in one place.
The first part of the process differs slightly depending on your OS. The
later steps are identical, so we've covered those steps in one place.
#### Linux
1. Download the pip installer from https://bootstrap.pypa.io/get-pip.py
1. Install `pip` locally instead of system-wide
1. `python ./get-pip.py --user`
1. Install `virtualenv` package and create new virtual environment
1. `python -m pip install virtualenv --user`
1. `python -m virtualenv rsyslog-docs-build`
1. `source rsyslog-docs-build/bin/activate`
1. Install `git` for your distro. Because distros name the package differently,
you may need to substitute the name of the package from the examples
below with the name of the package for your distro.
1. Download the pip installer from https://bootstrap.pypa.io/get-pip.py.
2. Install `pip` locally instead of system-wide:
1. `python ./get-pip.py --user`
3. Install the `virtualenv` package and create a new virtual environment:
1. `python -m pip install virtualenv --user`
1. `python -m virtualenv rsyslog-docs-build`
1. `source rsyslog-docs-build/bin/activate`
4. Install `git` for your distro. Since distros name the package differently,
you may need to substitute the package name from the examples
below with the name of the package for your distro.
You will need to install Git in order to clone the project repo, manage
your changes and contribute them back for review and eventual inclusion
in the project.
You'll need to install Git to clone the project repo, manage
your changes, and contribute them back for review and eventual inclusion
in the project.
Example commands for installing Git:
Example commands for installing Git:
- Debian/Ubuntu: `apt-get install git-core`
- CentOS/RHEL: `yum install git`
- Debian/Ubuntu: `apt-get install git-core`
- CentOS/RHEL: `yum install git`
See the
[Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
chapter from [Pro Git 2](https://git-scm.com/book/) for additional examples.
See the
[Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
chapter from [Pro Git 2](https://git-scm.com/book/) for additional examples.
#### Windows
1. Download the pip installer from https://bootstrap.pypa.io/get-pip.py
1. Download and install Git for windows from https://git-scm.com/download/win
1. Install `pip` locally instead of system-wide
1. `c:\python27\python get-pip.py --user`
1. Install `virtualenv` package and create new virtual environment
1. `c:\python27\python -m pip install virtualenv --user`
1. `c:\python27\python -m virtualenv rsyslog-docs-build`
1. `rsyslog-docs-build\Scripts\activate.bat`
1. Download the pip installer from https://bootstrap.pypa.io/get-pip.py.
2. Download and install Git for Windows from https://git-scm.com/download/win.
3. Install `pip` locally instead of system-wide:
1. `c:\python27\python get-pip.py --user`
4. Install the `virtualenv` package and create a new virtual environment:
1. `c:\python27\python -m pip install virtualenv --user`
1. `c:\python27\python -m virtualenv rsyslog-docs-build`
1. `rsyslog-docs-build\Scripts\activate.bat`
#### Windows and Linux
1. Install `sphinx` package and any other project dependencies in our
new virtual environment instead of system-wide
1. `pip install -r requirements.txt`
1. Clone the official Git repo
1. `git clone https://github.com/rsyslog/rsyslog-doc.git`
1. Checkout either the current stable or development (aka, "master") branch
1. `cd rsyslog-doc`
1. `git checkout BRANCH_NAME_HERE`
- Choose the `v8-stable` branch for coverage of features currently
available in the latest stable release
- Choose the `master` branch for coverage of upcoming features and fixes
1. Optional: If you have previously cloned the repo, run `git pull` to update it
with new changes before continuing.
1. Install the `sphinx` package and any other project dependencies in our
new virtual environment instead of system-wide:
1. `pip install -r requirements.txt`
2. Clone the official Git repo:
1. `git clone https://github.com/rsyslog/rsyslog.git`
3. Check out either the current stable or development (aka, "master") branch:
1. `cd rsyslog/doc`
1. `git checkout BRANCH_NAME_HERE`
- Choose the `v8-stable` branch for coverage of features currently
available in the latest stable release.
- Choose the `master` branch for coverage of upcoming features and fixes.
4. **Optional:** If you've previously cloned the repo, run `git pull` to update it
with new changes before continuing.
### Generate documentation
1. Generate HTML format
1. `sphinx-build -b html source build`
1. Generate EPUB format
1. `sphinx-build -b epub source build`
1. Review generated contents
- Open rsyslog-doc/build/index.html in a browser
- Use Calibre, Microsoft Edge, Okular, Google Play Books or any other
EPUB compatible reader to view the rsyslog-doc/build/rsyslog.epub file
1. Generate HTML format:
1. `sphinx-build -b html source build`
2. Generate EPUB format:
1. `sphinx-build -b epub source build`
3. Review generated contents:
- Open `rsyslog/doc/build/index.html` in a browser.
- Use Calibre, Microsoft Edge, Okular, Google Play Books, or any other
EPUB compatible reader to view the `rsyslog/doc/build/rsyslog.epub` file.