mirror of
https://github.com/zealdocs/zeal.git
synced 2026-08-29 08:34:50 +08:00
docs: update readme, add contributing guide (#1909)
This commit is contained in:
Oleg Shparber
@@ -0,0 +1,6 @@
|
||||
# Inline HTML is used deliberately for the theme-aware screenshot and store badges.
|
||||
MD033: false
|
||||
|
||||
# Keep in sync with max_line_length in .editorconfig.
|
||||
MD013:
|
||||
line_length: 120
|
||||
@@ -0,0 +1,86 @@
|
||||
# Contributing to Zeal
|
||||
|
||||
Thanks for your interest in improving Zeal. This document covers the practical side: how to build the project, which
|
||||
conventions to follow, and what to expect from review.
|
||||
|
||||
## Before you start
|
||||
|
||||
Bug reports and small fixes can go straight to [GitHub issues](https://github.com/zealdocs/zeal/issues) or a pull
|
||||
request. For anything larger, such as a new feature or refactoring, please open an issue or a
|
||||
[discussion](https://github.com/zealdocs/zeal/discussions) first so we can agree on the approach before you spend
|
||||
time on the implementation.
|
||||
|
||||
Questions are welcome in [GitHub discussions](https://github.com/zealdocs/zeal/discussions) or on
|
||||
[Discord](https://go.zealdocs.org/l/discord). Project spaces follow a short
|
||||
[code of conduct](https://go.zealdocs.org/l/conduct).
|
||||
|
||||
## Development setup
|
||||
|
||||
Build dependencies are listed in the [README](README.md#build-dependencies), and platform-specific instructions are
|
||||
in the [wiki](https://github.com/zealdocs/zeal/wiki).
|
||||
|
||||
The repository includes a [justfile](https://just.systems/) with recipes for common tasks:
|
||||
|
||||
```shell
|
||||
just configure # configure a build directory
|
||||
just build # compile
|
||||
just run # compile and launch Zeal
|
||||
just test # configure, build, and run the test suite
|
||||
```
|
||||
|
||||
Recipes use the `dev` CMake preset by default; override it with `PRESET=release just build`. If you prefer plain
|
||||
CMake, the presets work on their own:
|
||||
|
||||
```shell
|
||||
cmake --preset dev
|
||||
cmake --build --preset dev
|
||||
```
|
||||
|
||||
## Code style
|
||||
|
||||
Formatting is defined by `.clang-format` and `.editorconfig`. Run clang-format on the code you change, and match the
|
||||
style of the surrounding code for anything the tools do not cover.
|
||||
|
||||
## Commits
|
||||
|
||||
Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): a type, an optional scope, and
|
||||
a short description in the imperative mood.
|
||||
|
||||
```text
|
||||
fix(core): guard setColorScheme behind Qt 6.8
|
||||
feat(ui): improve tab bar sizing and styling
|
||||
build(cmake): append to CMAKE_MODULE_PATH
|
||||
```
|
||||
|
||||
Common scopes are `app`, `core`, `ui`, `util`, `assets`, and `cmake`. When in doubt, `git log` has plenty of examples.
|
||||
|
||||
## Tests
|
||||
|
||||
Run the suite with `just test`. New logic in `src/libs` should come with tests where practical.
|
||||
|
||||
## Licensing
|
||||
|
||||
Zeal is licensed under GPL-3.0-or-later, and the repository follows the [REUSE](https://reuse.software/) specification:
|
||||
|
||||
* New source files need a copyright notice and an SPDX license identifier; copy them from an existing file:
|
||||
|
||||
```cpp
|
||||
// Copyright (C) Oleg Shparber, et al. <https://zealdocs.org>
|
||||
// SPDX-License-Identifier: GPL-3.0-or-later
|
||||
```
|
||||
|
||||
* If you bring in third-party code, add its license text to `LICENSES/` and declare it in `REUSE.toml`.
|
||||
|
||||
By submitting a contribution, you agree to provide it under the project license.
|
||||
|
||||
## Pull requests
|
||||
|
||||
* Keep pull requests small and focused; unrelated changes belong in separate PRs.
|
||||
* CI must pass. It runs builds for all supported platforms and CodeQL analysis.
|
||||
* Zeal is maintained in spare time, so a review can take a while. If a PR sits without a response for a couple of
|
||||
weeks, a polite ping is fine.
|
||||
|
||||
## Security
|
||||
|
||||
If you think you have found a security issue, please report it privately to <support@zealdocs.org> instead of
|
||||
opening a public issue.
|
||||
@@ -1,31 +1,63 @@
|
||||
# Zeal
|
||||
|
||||
[](https://github.com/zealdocs/zeal/releases)
|
||||
[](https://gitter.im/zealdocs/zeal)
|
||||
[](https://web.libera.chat/#zealdocs)
|
||||
[](https://telegram.me/zealdocsapp)
|
||||
[](https://twitter.com/zealdocs)
|
||||
[](https://go.zealdocs.org/l/discord)
|
||||
[](https://go.zealdocs.org/l/telegram)
|
||||
[](https://go.zealdocs.org/l/x)
|
||||
|
||||
[](https://github.com/zealdocs/zeal/releases)
|
||||
[](https://github.com/zealdocs/zeal/actions/workflows/build-check.yaml)
|
||||
[](COPYING)
|
||||
|
||||
Zeal is a simple offline documentation browser inspired by [Dash](https://kapeli.com/dash).
|
||||
Zeal is an offline documentation browser: your personal reference library, searchable in an instant and available
|
||||
without a connection. Originally inspired by [Dash](https://kapeli.com/dash), it supports the same docset format.
|
||||
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="assets/screenshots/readme-dark.png">
|
||||
<img alt="Zeal showing instant search results across multiple docsets" src="assets/screenshots/readme-light.png">
|
||||
</picture>
|
||||
|
||||
## Download
|
||||
|
||||
Get binary builds for Windows and Linux from the [download page](https://zealdocs.org/download.html).
|
||||
<a href="https://flathub.org/apps/org.zealdocs.Zeal">
|
||||
<img height="44" alt="Get it on Flathub" src="https://flathub.org/api/badge?svg&locale=en"/>
|
||||
</a>
|
||||
<a href="https://snapcraft.io/zeal">
|
||||
<img height="44" alt="Get it from the Snap Store"
|
||||
src="https://snapcraft.io/static/images/badges/en/snap-store-black.svg"/>
|
||||
</a>
|
||||
|
||||
Binary builds for Windows and other installation options are available on the
|
||||
[download page](https://zealdocs.org/download).
|
||||
|
||||
## How to use
|
||||
|
||||
After installing Zeal go to `File->Docset Library`, select the ones you want, and click the `Download` button.
|
||||
After installing Zeal, go to `File → Docset Library`, select the docsets you want, and click the `Download` button.
|
||||
|
||||
### Query and filter docsets
|
||||
|
||||
Limit the search scope by prefixing your query with a docset name and a colon:
|
||||
|
||||
`cpp:vector`
|
||||
|
||||
To search multiple docsets, separate them with a comma:
|
||||
|
||||
`python,django:string`
|
||||
|
||||
### Command line
|
||||
|
||||
You can also start Zeal with a query from the command line:
|
||||
|
||||
`zeal python:pprint`
|
||||
|
||||
## How to compile
|
||||
|
||||
Detailed, up-to-date build instructions for each platform are available in the
|
||||
[wiki](https://github.com/zealdocs/zeal/wiki). The bare minimum is described below.
|
||||
|
||||
### Build dependencies
|
||||
|
||||
* [CMake](https://cmake.org/).
|
||||
* [Qt](https://www.qt.io/) version 6.4.2 or above. Required module: Qt WebEngine Widgets.
|
||||
* [CMake](https://cmake.org/) and [Ninja](https://ninja-build.org/).
|
||||
* [Qt](https://www.qt.io/) version 6.4.2 or later. Required modules besides Qt Base: Svg, WebEngine.
|
||||
* [libarchive](https://libarchive.org/).
|
||||
* [SQLite](https://sqlite.org/).
|
||||
* Linux/BSD platforms: `extra-cmake-modules`.
|
||||
@@ -33,43 +65,37 @@ After installing Zeal go to `File->Docset Library`, select the ones you want, an
|
||||
|
||||
### Build instructions
|
||||
|
||||
```sh
|
||||
cmake -B build
|
||||
cmake --build build
|
||||
```shell
|
||||
cmake --preset release
|
||||
cmake --build --preset release
|
||||
```
|
||||
|
||||
More detailed instructions are available in the [wiki](https://github.com/zealdocs/zeal/wiki).
|
||||
|
||||
## Query & Filter docsets
|
||||
|
||||
You can limit the search scope by using ':' to indicate the desired docsets:
|
||||
|
||||
`java:BaseDAO`
|
||||
|
||||
You can also search multiple docsets separating them with a comma:
|
||||
|
||||
`python,django:string`
|
||||
|
||||
## Command line
|
||||
|
||||
If you prefer, you can start Zeal with a query from the command line:
|
||||
|
||||
`zeal python:pprint`
|
||||
The resulting binary is `build/release/zeal` (`zeal.exe` on Windows).
|
||||
|
||||
## Create your own docsets
|
||||
|
||||
Follow instructions in the [Dash docset generation guide](https://kapeli.com/docsets).
|
||||
Follow the instructions in the [Dash docset generation guide](https://kapeli.com/docsets).
|
||||
|
||||
## Contact and Support
|
||||
## Contributing
|
||||
|
||||
We want your feedback! Here's a list of different ways to contact developers and request help:
|
||||
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to build Zeal, the conventions to follow,
|
||||
and what to expect from review.
|
||||
|
||||
## Contact and support
|
||||
|
||||
Ways to get help or reach the developers:
|
||||
|
||||
* Report bugs and submit feature requests to [GitHub issues](https://github.com/zealdocs/zeal/issues).
|
||||
* Reach developers and other Zeal users in `#zealdocs` IRC channel on [Libera Chat](https://libera.chat) ([web client](https://web.libera.chat/#zealdocs)).
|
||||
* Ask any questions in our [GitHub discussions](https://github.com/zealdocs/zeal/discussions).
|
||||
* Do not forget to follow [@zealdocs](https://twitter.com/zealdocs) on Twitter!
|
||||
* Finally, for private communication shoot an email to <support@zealdocs.org>.
|
||||
* Ask questions in [GitHub discussions](https://github.com/zealdocs/zeal/discussions).
|
||||
* Chat with developers and other Zeal users on [Discord](https://go.zealdocs.org/l/discord).
|
||||
* Subscribe to the [Telegram channel](https://go.zealdocs.org/l/telegram) for announcements.
|
||||
* Follow [@zealdocs](https://go.zealdocs.org/l/x) on X for news and updates.
|
||||
* Email <support@zealdocs.org> for anything private or sensitive.
|
||||
|
||||
## License
|
||||
|
||||
This software is licensed under the terms of the GNU General Public License version 3 (GPLv3) or later. Full text of the license is available in the [COPYING](COPYING) file and [online](https://www.gnu.org/licenses/gpl-3.0.html).
|
||||
This software is licensed under the terms of the GNU General Public License version 3 (GPLv3) or later. Full text of
|
||||
the license is available in the [COPYING](COPYING) file and [online](https://www.gnu.org/licenses/gpl-3.0.html).
|
||||
|
||||
Bundled third-party components are licensed under their respective terms; the repository is
|
||||
[REUSE](https://reuse.software/)-compliant, with all license texts available in the [LICENSES](LICENSES) directory.
|
||||
|
||||
@@ -36,6 +36,7 @@ path = [
|
||||
".gitattributes",
|
||||
".github/**/*",
|
||||
".gitignore",
|
||||
".markdownlint.yaml",
|
||||
"CHANGELOG.md",
|
||||
"tools/cliff.toml",
|
||||
]
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 171 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 175 KiB |
Reference in New Issue
Block a user