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
by this README and other documentation linked from this file.
If you are new to rst and Sphinx, see the Sphinx documentation to get started: http://www.sphinx-doc.org/en/stable/contents.html
In the repo you will find a contrib
directory.
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 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.
In addition to the directions here, there is also a separate
BUILDS_README.md file for use by rsyslog-doc
team
members. This doc is used as a quick reference for those who regularly
provide dev and official release builds of the documentation.
master
branchmaster
branch while you wait for feedback from the doc team.master
branch.For small changes, the work can be done entirely 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 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.
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 issues tagged with good first issue or help wanted
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 to Stack Exchange.
These directions assume default installs of Python for Windows and Linux. Because the Sphinx project recommends using Python 2.7, that is what is shown here.
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 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 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.
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.
Download the pip installer from https://bootstrap.pypa.io/get-pip.py
Install pip
locally instead of system-wide
python ./get-pip.py --user
Install virtualenv
package and create new virtual environment
python -m pip install virtualenv --user
python -m virtualenv rsyslog-docs-build
source rsyslog-docs-build/bin/activate
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.
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.
Example commands for installing Git:
apt-get install git-core
yum install git
See the Installing Git chapter from Pro Git 2 for additional examples.
pip
locally instead of system-wide
c:\python27\python get-pip.py --user
virtualenv
package and create new virtual environment
c:\python27\python -m pip install virtualenv --user
c:\python27\python -m virtualenv rsyslog-docs-build
rsyslog-docs-build\Scripts\activate.bat
sphinx
package and any other project dependencies in our
new virtual environment instead of system-wide
pip install -r requirements.txt
git clone https://github.com/rsyslog/rsyslog-doc.git
cd rsyslog-doc
git checkout BRANCH_NAME_HERE
v8-stable
branch for coverage of features currently
available in the latest stable releasemaster
branch for coverage of upcoming features and fixesgit pull
to update it
with new changes before continuing.sphinx-build -b html source build
sphinx-build -b epub source build