From a5b795056365c110cac61eb9679b9a24d34c606e Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Tue, 11 Jun 2024 10:55:50 +0200 Subject: [PATCH 1/4] Add Gradle Cookbook landing and Cross-references --- docs/CONTRIBUTING.md | 46 +++++++++++++++---- docs/contributing/documentation/README.md | 26 +++++++---- docs/cookbook/CONTRIBUTING.md | 33 +++++++++++++ docs/cookbook/README.md | 56 +++++++++++++++++++++-- mkdocs.yml | 24 +++++----- 5 files changed, 153 insertions(+), 32 deletions(-) create mode 100644 docs/cookbook/CONTRIBUTING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 241aa19..3ed7ff9 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,14 +1,41 @@ -# Contributing to the Community Site +# Contributing to the Gradle Community Site + +[![a](https://img.shields.io/badge/slack-%23docs-brightgreen?style=flat&logo=slack)](./contributing/community-slack.md) Contributing to this site is easy! +We do not have so many newcomer friendly issues in this repository, +but you are welcome to submit any small and big patches! + +Many smaller changes can be done from a browser. Just submit a pull request to the respective repository. On the rop right corner you can also see the _Edit_ icons that will normally get you right to the content page. -We do not have so many newcomer friendly issues in this repository, -but you are welcome to submit any small and big patches! +For bigger changes, you can do the development locally, and it is documented below. + +## Communication channels + +- `#docs` on the [Gradle Community Slack](./contributing/community-slack.md) + +## Contributing Content -## Technology under the hood +### Contributing to Gradle Cookbok + +See the [Gradle Cookbook Contributor Guide](./cookbook/CONTRIBUTING.md). + +### Other locations + +The Gradle website is at the early stages of development, +and we do not have a fixed process and practices. +Just submit a pull request with a change. +Should youhave any concerns, let's discuss it on Slack or a GitHub issue. + +## Developing the site + +It is possible to deploy the site instance locally or inside a Dev Container. +The latter is a recommended approach. + +### Technology under the hood The community site is built with [MkDocs](https://www.mkdocs.org/), [MkDocs Multirepo Plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin/tree/main), @@ -16,16 +43,15 @@ and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material). So, it uses the Python technology stack instead of Gradle, but on the other hand we're leveraging one of the most powerful documentation engines. -## Preparing the environment - -It is possible to deploy the site instance locally or inside a Dev Container. +### Setting iup the environment -### Dev Container +#### Dev Containers This repository includes the Dev Container definition that you can use in Visual Studio Code or in IntelliJ Platform to spin up the local development environment. +The same Dev Container is used for CI/CD, and it is a recommended way of local development, -### Running locally +#### Running locally Requirements: @@ -40,7 +66,7 @@ pip install -r .devcontainer/requirements.txt mkdocs build ``` -## Local development +### Local development Once you have the ready to build environment, you can use `mkdocs build` to build the static site. diff --git a/docs/contributing/documentation/README.md b/docs/contributing/documentation/README.md index 8f681e9..b824964 100644 --- a/docs/contributing/documentation/README.md +++ b/docs/contributing/documentation/README.md @@ -7,23 +7,33 @@ All contributions are welcome! - Join the community Slack workspace - Use the `#docs` channel to discuss any documentation matters -- If your pull request gets stuck, do not hesitate to ask in `#docs` or in `#contributing` channels +- If your pull request gets stuck, do not hesitate to ask in the `#docs` or `#contributing` channels ## Locations -- [Contributing to the Gradle Build Tool documentation](../../gradle/CONTRIBUTING/#contributing-to-documentation) - - - This repository includes Gradle documentation sources, including but not limited to: User Manual, DSL Reference, documentation for core plugins and Javadoc - - Implementation: Asciidoc + custom documentation engine +- [Gradle Build Tool - User Manual on docs.gradle.org/](https://docs.gradle.org/) + - This site includes main Gradle documentation sources, including but not limited to: User Manual, DSL Reference, documentation for core plugins and Javadoc + - Implementation: Asciidoc + custom documentation engine + - [Contributor Guide](../../gradle/CONTRIBUTING/#contributing-to-documentation) +- [Gradle Cookbook](../../cookbook/README.md) - a collection of recipes, guides and examples for the Gradle Build Tool. + - This is an additional solution-based documentation + - Implementation: MkDocs + Material for MkDocs + - [Contributor Guide](../../cookbook/CONTRIBUTING.md) - Plugin documentation - Documentation for the key plugins is provided by the Gradle Build Tool repo. For other plugins, see their repositories for the docs and contributing guidelines. - - Implementation: most plugins use simple documentation pages in GitHub-flavored Markdown (`README.md`). -- [Contributing to the Community site](../../CONTRIBUTING.md) - - Community resources on this website - - Implementation - Markdown + MkDocs + - Implementation: most plugins use simple documentation pages in GitHub-flavored Markdown (`README.md`). +- [Gradle Community Site](https://community.gradle.org/) - + Community resources, including [Gradle Cookbook](../../cookbook/README.md) and top-level [Gradle Contributor Guide](../README.md) + - Implementation - Markdown + MkDocs + - [Contributor Guide](../../CONTRIBUTING.md) ## Tools In Gradle we use a diverse set of tooling for documentation development. +We use both Markdown and Asciidoc for writing, +with MkDocs, Jekyll and Gradle Asciidoc Plugin being our main tools for documentation. +We also use other tools like Dokka, Javadoc, OpenAPI specifications, etc. + Many small patches can be just submitted from the GitHub web editor. For bigger patches and local development, see the referenced contributing guidelines. diff --git a/docs/cookbook/CONTRIBUTING.md b/docs/cookbook/CONTRIBUTING.md new file mode 100644 index 0000000..51480eb --- /dev/null +++ b/docs/cookbook/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing to the Gradle Cookbook + +[![a](https://img.shields.io/badge/slack-%23docs-brightgreen?style=flat&logo=slack)](./contributing/community-slack.md) + + +The Gradle Cookbook is under active development. +Any contributions are welcome! + +## Discuss + +- `#docs` on the [Gradle Community Slack](../contributing/community-slack.md) +- [GitHub Issues](https://github.com/gradle/community/issues) + +## HOWTOs + +### Editing and Adding Pages + +A few tips: + +- All the pages on this site are just Markdown +- If needed, we can a lot of machineryy reserved, e.g. for including code templates, macros, etc. + And we can add more MkDocs plugins if needed. +- The Table of Contents is currently located in [mkdocs.yml](../mkdocs.yml). + When adding new pages, please update the ToC so that it is discoverable. + +### Adding New Categories + +At the moment, we just add categories as convenient based opn the consensus. +If you add a new major category, better to discuss it in advance. + +## References + +- [Main community.gradle.org contributor guide](../CONTRIBUTING.md) - describes how to contribute in general, and how to set up the local environment if needed diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md index a3f96a0..4daa4b1 100644 --- a/docs/cookbook/README.md +++ b/docs/cookbook/README.md @@ -1,6 +1,56 @@ # The Gradle Cookbook -This is a collection of guides and examples for the Gradle Build Tool. +Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. +The goal of this portal is to offer solution-based documentation for end users, +including but not limited to key use cases like +publishing to Maven Central, +CI/CD tool and IDE integrations, +support for languages and frameworks, +troubleshooting Gradle Build Tool, +etc. -## Table of contents -* [Gradle Built Tool on CI](/community/cookbook/ci/jenkins/) \ No newline at end of file +In this document, _Gradle Build Tool_ is abbreviated _Gradle_. + +!!! note + The Gradle Cookbook is under active development. + Its structure and links may change, and we're working on adding more content. + Any contributions are welcome, see the [Contributor Guide](./CONTRIBUTING.md)! + +## Why and How? + +The Gradle Build Tool ecosystem is huge, it includes many plugins, integrations, developer tools and other components. +Not all of them can be covered in the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html) +which represents core documentation maintained for each Gradle release. +Moreover, being tied to the Gradle release contribution process and the release cycle makes it more difficult to contribute there. +Even for us, it has been difficult to maintain documentation in such a way, +and many pages have been quite outdated. + +So, we decided to build a second resource as an extension to the Gradle User Manual, +with the following in mind: + +- Gradle Cookbook remains an official resource under `community.gradle.org`. + It is not a second-class citizen, just another structure not tied to the Gradle release cycle +- Pages should be focused on offering solutions to end users for particular use cases, + hence the _Cookbook_ +- We follow the Wiki-alike collaboration style, + with a lower barrier to contribute than `gradle/gradle`. + Some sections can get explicit maintainers/reviewers over time. +- We use Documentation-as-Code, with simple Markdown or Asciidoc files used as a source +- Minimizing duplication. + We can include documentation from other sources under the [Gradle GitHub organization](https://github.com/gradle/) + +## Table of Contents + +- [Gradle Built Tool on CI](/community/cookbook/ci/jenkins/) + +## Contributing + +Contributions are welcome! +You can extend the Cookbook by adding new recipes, updating the existing ones, +or even creating whole new sections. +Check out the [Contributor Guide](./CONTRIBUTING.md) for more information. + +## References + +- [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html) +- [Other Documentation Locations](../contributing/documentation/README.md/#locations) diff --git a/mkdocs.yml b/mkdocs.yml index 149780f..469fd4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,13 +53,12 @@ theme: - search.suggest - toc.follow - toc.integrate - palette: - + palette: - scheme: default media: "(prefers-color-scheme: light)" primary: custom toggle: - icon: material/brightness-7 + icon: material/brightness-7 name: Switch to dark mode - scheme: slate @@ -98,19 +97,20 @@ extra: - icon: fontawesome/brands/mastodon link: https://mastodon.social/@Gradle name: Mastodon + analytics: + provider: google + property: G-7W7NC6YNPT -analytics: - provider: google - property: G-7W7NC6YNPT - nav: - Home: README.md - Cookbook: + - Overview: cookbook/README.md - Gradle on CI: - Jenkins: cookbook/ci/jenkins.md - TeamCity: cookbook/ci/teamcity.md - GitHub Actions: cookbook/ci/github-actions.md - Travis CI: cookbook/ci/travis-ci.md + - Contributing: cookbook/CONTRIBUTING.md - Participate: - Getting Started: contributing/README.md - Community Slack: contributing/community-slack.md @@ -144,7 +144,7 @@ nav: # - Develocity: https://gradle.com/develocity # - Service Providers: https://gradle.org/services/ # - Training: https://gradle.org/courses - + plugins: - search - autorefs @@ -155,7 +155,7 @@ plugins: - social - group: enabled: !ENV [FULL_BUILD, true] - plugins: + plugins: - multirepo: cleanup: false keep_docs_dir: true @@ -179,14 +179,15 @@ plugins: imports: [ "README.md", "*" ] - redirects: - redirect_maps: - + redirect_maps: + # Markdown markdown_extensions: - pymdownx.highlight: anchor_linenums: true line_spans: __span pygments_lang_class: true + - pymdownx.details - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences @@ -194,4 +195,5 @@ markdown_extensions: alternate_style: true - toc: permalink: '#' + - admonition - attr_list From a64f6288b754f9f2c76aa4e192bad882a855e8db Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Tue, 11 Jun 2024 11:27:18 +0200 Subject: [PATCH 2/4] Add front matter to the Cookbook section --- docs/cookbook/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md index 4daa4b1..c287bf7 100644 --- a/docs/cookbook/README.md +++ b/docs/cookbook/README.md @@ -1,4 +1,8 @@ -# The Gradle Cookbook +--- +title: "The Gradle Cookbook" +description: > + Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. +--- Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. The goal of this portal is to offer solution-based documentation for end users, From 4cb235ca75338ae8151046bf66c20514cfb3a872 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Tue, 11 Jun 2024 17:24:45 +0200 Subject: [PATCH 3/4] Apply suggestions from review by @lkasso Co-authored-by: Laura Kassovic --- docs/CONTRIBUTING.md | 23 ++++++++++++----------- docs/contributing/documentation/README.md | 4 ++-- docs/cookbook/CONTRIBUTING.md | 10 +++++----- docs/cookbook/README.md | 6 +++--- 4 files changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3ed7ff9..32bf50b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -3,15 +3,16 @@ [![a](https://img.shields.io/badge/slack-%23docs-brightgreen?style=flat&logo=slack)](./contributing/community-slack.md) Contributing to this site is easy! -We do not have so many newcomer friendly issues in this repository, -but you are welcome to submit any small and big patches! +While we may not have many issues for newcomers, +we welcome all contributions, big or small. -Many smaller changes can be done from a browser. +Many minor changes can be made directly from your browser. Just submit a pull request to the respective repository. On the rop right corner you can also see the _Edit_ icons that will normally get you right to the content page. -For bigger changes, you can do the development locally, and it is documented below. +For bigger changes, you can develop locally. +Detailed instructions are provided below. ## Communication channels @@ -25,15 +26,15 @@ See the [Gradle Cookbook Contributor Guide](./cookbook/CONTRIBUTING.md). ### Other locations -The Gradle website is at the early stages of development, -and we do not have a fixed process and practices. -Just submit a pull request with a change. -Should youhave any concerns, let's discuss it on Slack or a GitHub issue. +The Gradle website is in the early stages of development, +and we do not have fixed processes and practices yet. +Just submit a pull request with your change. +If you have any concerns, let's discuss them on Slack or in a GitHub issue. ## Developing the site It is possible to deploy the site instance locally or inside a Dev Container. -The latter is a recommended approach. +The latter is the recommended approach. ### Technology under the hood @@ -43,13 +44,13 @@ and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material). So, it uses the Python technology stack instead of Gradle, but on the other hand we're leveraging one of the most powerful documentation engines. -### Setting iup the environment +### Setting up the environment #### Dev Containers This repository includes the Dev Container definition that you can use in Visual Studio Code or in IntelliJ Platform to spin up the local development environment. -The same Dev Container is used for CI/CD, and it is a recommended way of local development, +The same Dev Container is used for CI/CD, and it is the recommended way for local development. #### Running locally diff --git a/docs/contributing/documentation/README.md b/docs/contributing/documentation/README.md index b824964..54fa678 100644 --- a/docs/contributing/documentation/README.md +++ b/docs/contributing/documentation/README.md @@ -31,8 +31,8 @@ All contributions are welcome! In Gradle we use a diverse set of tooling for documentation development. We use both Markdown and Asciidoc for writing, -with MkDocs, Jekyll and Gradle Asciidoc Plugin being our main tools for documentation. -We also use other tools like Dokka, Javadoc, OpenAPI specifications, etc. +with MkDocs, Jekyll, and the Gradle Asciidoc Plugin as our main tools for documentation. +Additionally, we utilize other tools such as Dokka, Javadoc, and OpenAPI specifications. Many small patches can be just submitted from the GitHub web editor. For bigger patches and local development, see the referenced contributing guidelines. diff --git a/docs/cookbook/CONTRIBUTING.md b/docs/cookbook/CONTRIBUTING.md index 51480eb..6d38f48 100644 --- a/docs/cookbook/CONTRIBUTING.md +++ b/docs/cookbook/CONTRIBUTING.md @@ -17,17 +17,17 @@ Any contributions are welcome! A few tips: -- All the pages on this site are just Markdown +- All the pages on this site are written in Markdown. - If needed, we can a lot of machineryy reserved, e.g. for including code templates, macros, etc. And we can add more MkDocs plugins if needed. - The Table of Contents is currently located in [mkdocs.yml](../mkdocs.yml). - When adding new pages, please update the ToC so that it is discoverable. +When adding new pages, please update the ToC to ensure they are discoverable. ### Adding New Categories -At the moment, we just add categories as convenient based opn the consensus. -If you add a new major category, better to discuss it in advance. +At the moment, we add categories based on consensus. +If you plan to add a new major category, it's better to discuss it in advance. ## References -- [Main community.gradle.org contributor guide](../CONTRIBUTING.md) - describes how to contribute in general, and how to set up the local environment if needed +- [Main community.gradle.org contributor guide](../CONTRIBUTING.md) - describes how to contribute and how to set up the local environment if needed diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md index c287bf7..ba22ee3 100644 --- a/docs/cookbook/README.md +++ b/docs/cookbook/README.md @@ -26,14 +26,14 @@ The Gradle Build Tool ecosystem is huge, it includes many plugins, integrations, Not all of them can be covered in the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html) which represents core documentation maintained for each Gradle release. Moreover, being tied to the Gradle release contribution process and the release cycle makes it more difficult to contribute there. -Even for us, it has been difficult to maintain documentation in such a way, -and many pages have been quite outdated. +Maintaining documentation has been challenging for us as well, +leading to many outdated pages. So, we decided to build a second resource as an extension to the Gradle User Manual, with the following in mind: - Gradle Cookbook remains an official resource under `community.gradle.org`. - It is not a second-class citizen, just another structure not tied to the Gradle release cycle + It is not a second-class citizen, just another structure that is not tied to the Gradle release cycle - Pages should be focused on offering solutions to end users for particular use cases, hence the _Cookbook_ - We follow the Wiki-alike collaboration style, From 88be2985f0d7b68337a005a4eab704ae5a2c509b Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Tue, 11 Jun 2024 17:30:33 +0200 Subject: [PATCH 4/4] Apply suggestions from review by @lkasso Co-authored-by: Laura Kassovic --- docs/cookbook/CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/cookbook/CONTRIBUTING.md b/docs/cookbook/CONTRIBUTING.md index 6d38f48..63fd635 100644 --- a/docs/cookbook/CONTRIBUTING.md +++ b/docs/cookbook/CONTRIBUTING.md @@ -18,8 +18,7 @@ Any contributions are welcome! A few tips: - All the pages on this site are written in Markdown. -- If needed, we can a lot of machineryy reserved, e.g. for including code templates, macros, etc. - And we can add more MkDocs plugins if needed. +- If needed, we have various tools available, such as code templates and macros, and we can add more MkDocs plugins if necessary. - The Table of Contents is currently located in [mkdocs.yml](../mkdocs.yml). When adding new pages, please update the ToC to ensure they are discoverable.