diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..0b3763ab --- /dev/null +++ b/.markdownlint.yaml @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..6cdf8951 --- /dev/null +++ b/CONTRIBUTING.md @@ -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. + // 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 instead of +opening a public issue. diff --git a/README.md b/README.md index f8a9342c..981fbeca 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,63 @@ # Zeal -[![Changelog](https://img.shields.io/github/release/zealdocs/zeal.svg?style=flat-square)](https://github.com/zealdocs/zeal/releases) -[![Gitter](https://img.shields.io/gitter/room/zealdocs/zeal.svg?style=flat-square)](https://gitter.im/zealdocs/zeal) -[![IRC](https://img.shields.io/badge/chat-on%20irc-blue.svg?style=flat-square)](https://web.libera.chat/#zealdocs) -[![Telegram Channel](https://img.shields.io/badge/follow-on%20telegram-179cde.svg?style=flat-square)](https://telegram.me/zealdocsapp) -[![Twitter](https://img.shields.io/badge/follow-on%20twitter-1da1f2.svg?style=flat-square)](https://twitter.com/zealdocs) +[![Discord](https://img.shields.io/badge/chat-on%20discord-5865f2?style=flat-square)](https://go.zealdocs.org/l/discord) +[![Telegram Channel](https://img.shields.io/badge/follow-on%20telegram-179cde?style=flat-square)](https://go.zealdocs.org/l/telegram) +[![X (Twitter)](https://img.shields.io/badge/follow-on%20x-000000?style=flat-square)](https://go.zealdocs.org/l/x) +[![Release](https://img.shields.io/github/release/zealdocs/zeal?style=flat-square)](https://github.com/zealdocs/zeal/releases) [![Build Check](https://img.shields.io/github/actions/workflow/status/zealdocs/zeal/build-check.yaml?style=flat-square)](https://github.com/zealdocs/zeal/actions/workflows/build-check.yaml) +[![License](https://img.shields.io/github/license/zealdocs/zeal?style=flat-square)](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. -![Screenshot](https://github.com/zealdocs/zeal/assets/714940/e8443bb4-ccb9-469b-89d6-b5b3bfc7e239) + + + Zeal showing instant search results across multiple docsets + ## Download -Get binary builds for Windows and Linux from the [download page](https://zealdocs.org/download.html). + + Get it on Flathub + + + Get it from the Snap Store + + +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 . +* 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 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. diff --git a/REUSE.toml b/REUSE.toml index 41f0e43c..10a04318 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -36,6 +36,7 @@ path = [ ".gitattributes", ".github/**/*", ".gitignore", + ".markdownlint.yaml", "CHANGELOG.md", "tools/cliff.toml", ] diff --git a/assets/screenshots/readme-dark.png b/assets/screenshots/readme-dark.png new file mode 100644 index 00000000..48b9a2ea Binary files /dev/null and b/assets/screenshots/readme-dark.png differ diff --git a/assets/screenshots/readme-light.png b/assets/screenshots/readme-light.png new file mode 100644 index 00000000..1a3f8459 Binary files /dev/null and b/assets/screenshots/readme-light.png differ