{"id":19378901,"url":"https://github.com/linbit/linbit-documentation","last_synced_at":"2025-02-24T16:26:16.718Z","repository":{"id":26477697,"uuid":"103639477","full_name":"LINBIT/linbit-documentation","owner":"LINBIT","description":"Official DRBD documentation","archived":false,"fork":false,"pushed_at":"2024-04-17T19:34:16.000Z","size":19070,"stargazers_count":34,"open_issues_count":1,"forks_count":20,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-04-17T22:55:34.924Z","etag":null,"topics":["documentation","drbd"],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LINBIT.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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}},"created_at":"2017-09-15T09:27:12.000Z","updated_at":"2024-04-23T14:12:55.686Z","dependencies_parsed_at":"2023-01-14T07:00:55.462Z","dependency_job_id":"759620fd-3a0c-4c4c-be65-2b36c651193f","html_url":"https://github.com/LINBIT/linbit-documentation","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/LINBIT%2Flinbit-documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LINBIT%2Flinbit-documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LINBIT%2Flinbit-documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LINBIT%2Flinbit-documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LINBIT","download_url":"https://codeload.github.com/LINBIT/linbit-documentation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240511944,"owners_count":19813384,"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":["documentation","drbd"],"created_at":"2024-11-10T09:07:52.208Z","updated_at":"2025-02-24T16:26:16.684Z","avatar_url":"https://github.com/LINBIT.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Using the LINBIT Documentation Framework\n\n== Rendered version\n\n=== User's Guides\nIf you are interested in the rendered version of the User's Guide, please read them at\nhttps://docs.linbit.com[docs.linbit.com].\n\n=== Tech Guides\nYou can download PDF versions for free from https://www.linbit.com/tech-guides-overview/[our home page].\n\n== Build dependencies\nIf you have `docker`, execute `make dockerimage`, which will generate a \"linbit-documentation\" base\nDocker image containing all the dependencies for generating HTML and PDF outputs.\n\nOtherwise you will need `GNU make` and you have to install the following dependencies:\n\n=== HTML targets (UGs/tech-guides)\n- asciidoctor\n\n=== HTML targets (man pages)\n- mandoc\n\n=== PDF targets\n- https://github.com/asciidoctor/asciidoctor-pdf[asciidoctor-pdf]\n\n== Fonts\n=== LINBIT Fonts\nWe do not publish the official LINBIT fonts that are used to generate official LINBIT\ndocumentation. Public projects have to be able to generate PDFs without LINBIT fonts, If you\nhave a public project, create a `linbit-fonts` directory in the documentation root directory\n(`linbit-documentation`) and then download and extract into that directory the\nhttps://github.com/asciidoctor/asciidoctor-pdf/tree/main/data/fonts[necessary M+ fonts] that are\nused as a fallback font set:\n\n- mplus1mn-bold-subset.ttf\n- mplus1mn-bold_italic-subset.ttf\n- mplus1mn-italic-subset.ttf\n- mplus1mn-regular-subset.ttf\n\nPublic projects should also download the GNU Unifont font (available\nhttps://ftp.gnu.org/gnu/unifont/[here]), rename the downloaded file `unifont.ttf`, and put it\ninto a `linbit-fonts` directory, along with the M+ font files.\n\nPrivate projects are allowed to fail if the `linbit-fonts` directory does not exist.\nActually they *should* fail, which is the default anyways.\n\nIf you build official PDFs/private projects, make sure that you cloned the internal `linbit-fonts` repository.\n\n=== Japanese Fonts\nBefore you generate PDF versions of the Japanese user's guides, download this\nhttps://packages.linbit.com/public/genshingothic-20150607.zip[zip archive]. Extract the archive to a\n`fonts/genshingothic-fonts` directory in the root of the documentation directory\n(`linbit-documentation`).\n\n=== Chinese Fonts\nBefore you generate PDF versions of the Chinese user's guides, download these \"Simplified\nChinese\" (`sc`) font files:\n\n- https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf\n- https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/Mono/NotoSansMonoCJKsc-VF.ttf\n\nAfter downloading these files, place them in a `fonts/noto-cn` directory in the root of the\ndocumentation directory (`linbit-documentation`).\n\n=== Using Docker to Generate PDF Versions of Translated Documentation\n\nFor Japanese and Chinese translated documentation, you can simply build the\n`linbit-documentation` Docker image and the build process will bring in the necessary font files\nfor Japanese and Chinese PDF documentation building, as described above. You can then use the\n`-docker` make targets for various documentation building tasks, while setting `lang=`\nappropriately.\n\n== Tech Guides\nWe do not publish the source of our tech guides, make sure that you cloned the internal `tech-guides` repository.\n\n== Makefile interface/API for projects\n\nProjects are organized in subdirectories, for example the user's guide for DRBD 9 is in `UG9`. The top level\n`Makefile` contains HTML and PDF targets for these (e.g., `make UG9-pdf-finalize`). The final output is\ngenerated in `$project/$lang/output-$format-finalize` (e.g. `UG9/en/output-pdf-finalize`).\n\nEvery project needs a *proper* `Makefile` that has the following targets:\n\n- `pdf`\n- `pdf-finalize`\n- `html`\n- `html-finalize`\n\nIf a project only generates PDF output, implement the HTML targets as empty.\n\n=== PDF and HTML targets\nThese generate their output to `output-$format`. It is perfectly fine that these directories contain temporary\nfiles like symlinks. As already written, we want proper ``Makefile``s, so if the source does not change\nre-executing these targets should only process files that changed.\n\n=== pdf-finalize and html-finalize targets\nThese generate their output to `output-$format-finalize`. This is the *final* output. The one that is\npublished to a web page/sent to a web developer. For example this generates tar archive files for `UG9` that can be\nsent to someone who puts it on the web page.\n\nIt is usually the final target that is executed after multiple iterations of `make pdf`/`make html` and it is\nfine if that target alters the content of `output-$format` to generate `output-$format-finalize`. If possible\nit should not, but it is not a strict requirement.\n\n=== Docker targets\nThe top-level ``Makefile`` also contains targets that end in \"-docker\". These can be used to generate the\noutput with the previously described \"linbit-documentation\" base image. For example one can execute\n`make UG9-html-finalize-docker`.\n\nThe `-docker` `make` targets depend on the \"local\" `make` targets. Using the Docker targets is preferred, for consistent results, unless you have a reason not to use them. As of January 2023, local `make` targets are untested and unsupported, except as they are run through the `linbit-documentation` Docker image.\n\n=== Internationalization\nThe English version is the default, but if you want to build the Japanese version, you have to set the `make`\nvariable \"lang\" accordingly (e.g., `make UG9-html-finalize-docker lang=ja`).\nJapanese version is created by English `.adoc` files and Japanese `.po` files.\nPot files used for localization can be created by the pot target,\n(e.g, `make UG9-pot-docker).\nMake sure created pot files include correct sentences.\n\n[[work-public]]\n== Working on a Public Project\n- `cd` to the project (e.g, `cd UG9/en`)\n- modify sources accordingly\n- `make pdf` or `make html`\n\nOutput is generated in `output-$format`. These directories (in contrast to `output-$format-finalize`) can\ncontain temporary files (symlinks, processed adoc files,...). When you are satisfied, `make $format-finalize`,\nto generate the final output in `output-$format-finalize`.\n\n== Working on a Private Project\n- make sure you are at the top-level of the framework (`linbit-documentation`)\n- `git clone` the private project\n- follow \u003c\u003cwork-public\u003e\u003e\n\n== Style:\n- http://asciidoctor.org/docs/asciidoc-writers-guide/[Read it, learn it, live it!]\n- Hostnames: 'bob' =\u003e 'bob'\n- Commands: \\`rm -rf` =\u003e `rm -rf`\n- DRBD states: \\_Primary_ =\u003e _Primary_\n- Blocks: Add newline before and after the block. Delimit blocks using four (4) hyphens only. For example:\n```\n* Re-enable your DRBD resource:\n\n----\n# drbdadm up \u003cresource\u003e\n----\n\n* On one node, promote the DRBD resource:\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinbit%2Flinbit-documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinbit%2Flinbit-documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinbit%2Flinbit-documentation/lists"}