Repository files navigation

Documentation for rsyslog is generated with the (Python) Sphinx documentationprocessor. Documentation for thersyslog-doc project itself is providedby 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 acontrib directory.

Although content in this directory is part of the officialrsyslog-docrepo, the status is different. While other content in this repo is fullysupported by the dev team, content in thecontrib directory is supportedprimarily by the contributor who provided it.

Content may range from small one-off scripts to tools for automating buildsof the docs. See thecontrib README for details.

If you have new things to add to this area, please follow the directionson this page for contributing to the docs and submit your changes asa new Pull Request.

In addition to the directions here, there is also a separateBUILDS_README.md file for use byrsyslog-doc teammembers. This doc is used as a quick reference for those who regularlyprovide dev and official release builds of the documentation.

1. Login with a GitHub account
2. Fork the officialhttps://github.com/rsyslog/rsyslog-doc repo
3. Create a new branch off of the latestmaster branch
4. Make your changes
5. Commit to the new branch in your fork
6. Submit a Pull Request (PR) for review(https://github.com/rsyslog/rsyslog-doc/pulls)
7. Stop making any changes to your new branch now that you have submitted aPull Request for review. Instead, create a new branch from yourmasterbranch while you wait for feedback from the doc team.
8. A member of the team will review and offer feedback on your work. Afterfeedback has been given and you have made all necessary changes, yourPR will be accepted and merged into the officialmaster branch.
9. At this point, delete your branch that you submitted the PR from and starta new one for the next round of work.

For small changes, the work can be done entirely through the GitHub webinterface. For larger changes, some familiarity with Git is useful, thoughsome editors such as Atom or Visual Studio Code make interfacing with Giteasier for newcomers.

Before you begin your work, you are encouraged to review the existing PRs andopen issues so that you can coordinate your work with other contributors.

Please reach out if you have any questions as you work through making yourchanges.

Tip: If you would like something less complex to get started with, please seeissues tagged withgood first issueorhelp wanted

While working on changes to the docs, you are encouraged to seek input fromother members of the community. This can be done via the mailing list, hereon GitHub by submitting a new issue or (experimentally) byposting a questionto Stack Exchange.

• Mailing list:http://lists.adiscon.net/mailman/listinfo/rsyslog
• Stack Exchange (experimental)
  • Ask a question
  • View existing questions

These directions assume default installs of Python for Windows and Linux.Because theSphinx project recommends using Python 2.7,that is what is shown here.

• You wish to install thepip Python package as a standard user, which placesinstalled packages into that user's home directory. Remove the--userflag if you wish to install system-wide for all users instead.

• You wish to use a virtual environment to install Sphinx and its dependenciesinto a dedicated environment instead of installing alongside packages thatwere installed system-wide or to the user's home directory with the--userflag. If you wish to install thesphinx package and all dependent packagesfor all users of the system, then you will need to run the packageinstallation commands as an elevated user account (e.g.,sudo,su orwith administrator rights on a Windows system).

• You are running through these steps for the first time. Leave out the stepsinvolving installation of packages and applications if generating an updatedcopy of the documentation.

The first part of the process is a little different depending on your OS. Thelater steps are identical, so those steps have been covered in one place.

1. Download the pip installer fromhttps://bootstrap.pypa.io/get-pip.py

2. Installpip locally instead of system-wide

   1. python ./get-pip.py --user

3. Installvirtualenv package and create new virtual environment

   1. python -m pip install virtualenv --user
   2. python -m virtualenv rsyslog-docs-build
   3. source rsyslog-docs-build/bin/activate

4. Installgit for your distro. Because distros name the package differently,you may need to substitute the name of the package from the examplesbelow with the name of the package for your distro.

   You will need to install Git in order to clone the project repo, manageyour changes and contribute them back for review and eventual inclusionin the project.

   Example commands for installing Git:

   • Debian/Ubuntu:apt-get install git-core
   • CentOS/RHEL:yum install git

   See theInstalling Gitchapter fromPro Git 2 for additional examples.

1. Download the pip installer fromhttps://bootstrap.pypa.io/get-pip.py
2. Download and install Git for windows fromhttps://git-scm.com/download/win
3. Installpip locally instead of system-wide
   1. c:\python27\python get-pip.py --user
4. Installvirtualenv package and create new virtual environment
   1. c:\python27\python -m pip install virtualenv --user
   2. c:\python27\python -m virtualenv rsyslog-docs-build
   3. rsyslog-docs-build\Scripts\activate.bat

1. Installsphinx package and any other project dependencies in ournew 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-doc.git
3. Checkout either the current stable or development (aka, "master") branch
   1. cd rsyslog-doc
   2. git checkout BRANCH_NAME_HERE
      • Choose thev8-stable branch for coverage of features currentlyavailable in the latest stable release
      • Choose themaster branch for coverage of upcoming features and fixes
4. Optional: If you have previously cloned the repo, rungit pull to update itwith new changes before continuing.

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 otherEPUB compatible reader to view the rsyslog-doc/build/rsyslog.epub file