forgejo/docs
mpeter50 371dd96e3e
Clarify logging documentation (#21665)
My pull request changes the logging documentation that is visible here:
https://docs.gitea.io/en-us/logging-configuration/
The reason behind the changes is that for some time I've found the
logging documentation confusing, and wanted to give a try at making it
more clear.

---

If you find the existing changes to be ok, please don't merge yet, as I
have further ideas which I want to discuss with you before making the
changes.

### Swap the "Log Groups" and "Log outputs" sections.
I want to move the "Log outputs" section before the "Log Groups"
section. The reason is that the "Log Groups" section refers to ini
sections that are only later explained, and to concepts that are general
and should be documented in "Log outputs" or a different section.

This change is essentially a swap of the "Log Groups" and "Log outputs"
sections. That way the doumentation would follow the structure in which
the ini file is built: first explaining the outer sections, and then the
inner ones ([log], [log.name], [log.name.default], ...)

### Explain the workings of ambigous settings below the settings listing
Right now the basics of a setting is shown later than the explanation of
its special workings, for example with `FILE_NAME` at [the file output
mode](https://docs.gitea.io/en-us/logging-configuration/#file-mode)
(well, if the first changes are taken into account).

Currently I have `TODO` witten at 2 settings, which I have to figure out
how do they exactly work before I can document them.

### New section about [log]
New section after "Collecting Logs for Help" about how the top level
[log] itself works and what can go there.
Currently, variables that directly go into [log] are noted throughout
the whole document.

---

Please let me know what you think about the changes.

A counterargument that I myself see is that some of this is already
present in the cheatsheet, but I think it would be better to have [this
document](https://docs.gitea.io/en-us/logging-configuration/) as a
throrough explanation of how logging is configured, and the cheatsheet
would only have a short outline of the possible sections and variables.

Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
2022-11-22 09:04:29 +08:00
..
assets/js Add new JS linter rules (#17699) 2021-11-22 16:19:01 +08:00
content Clarify logging documentation (#21665) 2022-11-22 09:04:29 +08:00
layouts docs: move search input to navbar (#20551) 2022-08-08 15:27:04 +08:00
scripts Fix building of docs with latest hugo version (#3856) 2018-04-28 23:46:05 +03:00
static Refactor docs (#21627) 2022-10-31 23:16:19 +00:00
.gitignore Support Issue forms and PR forms (#20987) 2022-09-02 15:58:49 +08:00
config.yaml update current stable version 2022-10-15 22:04:25 -04:00
LICENSE Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
Makefile follow redirect when fetching theme archive (#15986) 2021-05-26 18:03:39 -04:00
README.md Update to docs README (#6221) 2019-03-01 15:39:30 -05:00
README_ZH.md update discord link (#10455) 2020-02-25 12:36:45 -05:00

Gitea: Docs

Join the chat at https://img.shields.io/discord/322538954119184384.svg

Hosting

These pages are hosted using netlifycms and get automatically updated on every push to the master branch.

Install

These pages use the Hugo static site generator. If you are planning to contribute you'll want to download and install Hugo on your local machine.

The installation of Hugo is out of the scope of this document, so please take the official install instructions to get Hugo up and running.

Development

To generate the website and serve it on localhost:1313 just execute this command and stop it with Ctrl+C:

make server

When you are done with your changes just create a pull request, after merging the pull request the website will be updated automatically.

Contributing

Fork -> Patch -> Push -> Pull Request

Authors

License

This project is under the Apache-2.0 License. See the LICENSE file for the full license text.

Copyright (c) 2016 The Gitea Authors <https://gitea.io>