{"id":20504038,"url":"https://github.com/icinga/icinga-docs-tools","last_synced_at":"2025-04-13T20:47:47.985Z","repository":{"id":23723086,"uuid":"97590647","full_name":"Icinga/icinga-docs-tools","owner":"Icinga","description":"Build environment for docs.icinga.com","archived":false,"fork":false,"pushed_at":"2025-02-27T15:23:55.000Z","size":621,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-13T20:47:39.643Z","etag":null,"topics":["icinga","mkdocs"],"latest_commit_sha":null,"homepage":"https://www.icinga.com/docs/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Icinga.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-18T11:33:09.000Z","updated_at":"2025-02-27T15:23:58.000Z","dependencies_parsed_at":"2023-02-14T08:01:07.900Z","dependency_job_id":"b118cca0-a994-4c9a-97ea-f4f92fc11c9c","html_url":"https://github.com/Icinga/icinga-docs-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Icinga%2Ficinga-docs-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Icinga%2Ficinga-docs-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Icinga%2Ficinga-docs-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Icinga%2Ficinga-docs-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Icinga","download_url":"https://codeload.github.com/Icinga/icinga-docs-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248782278,"owners_count":21160716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["icinga","mkdocs"],"created_at":"2024-11-15T19:35:50.623Z","updated_at":"2025-04-13T20:47:47.953Z","avatar_url":"https://github.com/Icinga.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Icinga Documentation\nThis repository includes scripts to build the documentation for all Icinga projects.\n\nThe `build-docs.rb` script clones the configured project to a certain directory and switches to the specified\nbranch. It searches for `*.md` files within the configured directory and creates documentation sections out of them.\nThe ordering is defined by the file names. The capitalized name of each file is used as a title for this documentation\nsection. The generates the `mkdocs.yml` file. \n\n## Usage\n``` bash\nUsage: build-docs.rb -c config.yml -t mkdocs.template.yml}\n    -f, --config FILENAME            Configuration file with project definition. Defaults to \"config.yml\"\n    -t, --template FILENAME          This file is used as template for the generated mkdocs.yaml. Defaults to \"mkdocs.template.yml\"\n    -h, --help                       Show this message\n```\n\n## Configuration\n\n### `config.yml`\nThis file defines generally for which project documentation should be build.\n\n\nGeneral settings:\n\n| Option        | Description                                                  |\n| ------------- | ------------------------------------------------------------ |\n| `site_name`   |  The `site_name` is displayed as title on the generated page |\n| `source_dir'` | Target directory to store the documentation source.          |\n| `site_dir`    | Target directory for generated html                          |\n| `project`     | General project settings                                     |\n\n\nProject settings:\n\n| Option           | Description                                                  |\n| --------------- | ------------------------------------------------------------ |\n| `git`           | Git repository to clone                                                                               |\n| `ref`           | Git branch or tag to checkout. For tags use `tags/v1.1.0` notation                                    |\n| `target`        | A unique name to define the target. This is added to `source_dir` and `site_dir`                      |\n| `docs_dir`      | Directory within the repository that includes documentation files. Eg. `doc`                          |\n| `latest`        | If set to `true`, this documentation will be marked as the latest. This is important for the URLs.    |\n| `subprojects`   | A project may include one ore more sub-projects.                                                      |\n\nSubprojects are optional. They allow you to display a project documentation within another project documentation.\nWe need this for Icinga Web 2, Icinga Director and other projects where we summarise multiple repositories into one documentation.\n\nExample: \n\n``` yaml\nsite_name: 'Icinga 2'\nsource_dir: 'www/source'\nsite_dir: 'www/html'\nproject:\n  git: 'https://github.com/Icinga/icinga2.git'\n  ref: 'support/2.7'\n  target: 'icinga2'\n  docs_dir: 'doc'\n  latest: true\n```\n\nExample with subprojects:\n\n``` yaml\nsite_name: 'Director'\nsource_dir: 'www/source'\nsite_dir: 'www/html'\nproject:\n  git: 'https://github.com/Icinga/icingaweb2-module-director.git'\n  ref: 'support/1.4'\n  target: 'director'\n  docs_dir: 'doc'\n  latest: true\n  subprojects:\n    PuppetDB:\n      git: 'https://github.com/Icinga/icingaweb2-module-puppetdb.git'\n      ref: 'master'\n      target: 'puppetdb'\n      docs_dir: 'puppetdb/doc'\n```\n\n### `mkdocs.template.yml`\nThis file is used as a template for the final `mkdocs.yml`. Default settings and some other configuration options are\nhere.\n\n### Run Development Server\nTo see a live preview of the documentation you can run a development server that will refresh automatically on changes.\n\n\n\nClone this repository and install dependencies:\n\n``` bash\nuser@localhost ~/ $ git clone https://github.com/Icinga/icinga-docs-tools.git\nuser@localhost ~/ $ cd icinga-docs-tools\nuser@localhost ~/ $ bundle install --path vendor\n```\n\nCreate and configure configuration file:\n\nBuild documentation: \n\n``` bash\nuser@localhost ~/ $ bundle exec build-docs.rb -f examples/businessprocess-latest.yml\n```\n\nRun server: \n\n``` bash\ndocker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:6.1.0\n```\n\nYou should be able to access the documentation now in your browser by calling the address https://localhost:8000\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficinga%2Ficinga-docs-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficinga%2Ficinga-docs-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficinga%2Ficinga-docs-tools/lists"}