{"id":23478445,"url":"https://github.com/easybuilders/easybuild-docs","last_synced_at":"2025-04-14T21:31:37.172Z","repository":{"id":62025121,"uuid":"555820401","full_name":"easybuilders/easybuild-docs","owner":"easybuilders","description":"EasyBuild documentation (mkdocs)","archived":false,"fork":false,"pushed_at":"2024-12-24T16:28:25.000Z","size":149965,"stargazers_count":3,"open_issues_count":47,"forks_count":24,"subscribers_count":15,"default_branch":"develop","last_synced_at":"2024-12-24T17:27:02.013Z","etag":null,"topics":["documentation","easybuild","markdown","mkdocs"],"latest_commit_sha":null,"homepage":"https://docs.easybuild.io","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/easybuilders.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","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":"2022-10-22T12:08:14.000Z","updated_at":"2024-12-19T20:16:40.000Z","dependencies_parsed_at":"2023-10-22T11:40:52.709Z","dependency_job_id":"a61cf399-f597-4180-accf-d0d72848116e","html_url":"https://github.com/easybuilders/easybuild-docs","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/easybuilders%2Feasybuild-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easybuilders%2Feasybuild-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easybuilders%2Feasybuild-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easybuilders%2Feasybuild-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/easybuilders","download_url":"https://codeload.github.com/easybuilders/easybuild-docs/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231143597,"owners_count":18334412,"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","easybuild","markdown","mkdocs"],"created_at":"2024-12-24T19:19:59.562Z","updated_at":"2024-12-24T19:20:05.684Z","avatar_url":"https://github.com/easybuilders.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EasyBuild documentation\n\nThis repository contains the *sources* of the EasyBuild documentation, which is hosted at \u003chttps://docs.easybuild.io\u003e.\n\n## Format\n\nThe documentation sources are located in the [docs subdirectory](https://github.com/easybuilders/easybuild-docs/tree/main/docs).\n\nThey are written in [MarkDown](https://daringfireball.net/projects/markdown) format, and rendered using [MkDocs](https://www.mkdocs.org),\nand the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material) theme.\n\nUseful links:\n\n- The Markdown Guide: \u003chttps://www.markdownguide.org\u003e\n- Reference guide for Material for MkDocs: \u003chttps://squidfunk.github.io/mkdocs-material/reference\u003e\n\n### Writing\n\nWhen writing content for the EasyBuild documentation, it is useful to get a live preview of how things will look.\n\nNext to the letting `mkdocs` serve a local copy of the full EasyBuild documentation so you can view it in your browser\n(see below), you can also use online services for this. This will allow you to see a live version of standard\nMarkdown, but it will not give you a live preview of the MkDocs specific Markdown extensions.\n\nAt \u003chttps://markdownlivepreview.com\u003e you can see a live preview while editing content in MarkDown format.\n\n[HackMD (https://hackmd.io)](https://hackmd.io) is a MarkDown note service which provides live previewing of\nthe rendered note while you edit in MarkDown format, and *collaborative editing* of content.\n\nCreate a new note via \u003chttps://hackmd.io/new\u003e to preview your content while editing it in MarkDown,\nand share the note URL with others if you would like to work together on some content.\n\nTo save work-in-progress notes and get back to them later, create a dedicated HackMD account,\nor sign in using your GitHub/Google/... account, via \u003chttps://hackmd.io/login\u003e.\n\n## Publishing\n\nThe documentation is automatically built and published to \u003chttps://docs.easybuild.io\u003e on every push to the `main` branch of this repository.\n\nThis is taken care of by the [`deploy` GitHub Actions workflow](https://github.com/easybuilders/easybuild-docs/tree/main/.github/workflows/deploy.yml).\n\n## Using `mkdocs`\n\n### Installing `mkdocs`\n\nTo install all the required `mkdocs` Python packages, use the provided [requirements.txt](https://github.com/easybuilders/easybuild-docs/tree/main/requirements.txt) file:\n\n```shell\npip install -r requirements.txt\n```\n\n### Building\n\nTo build the documentation, use:\n\n```shell\nmkdocs build\n```\n\nor use the `Makefile` that is provided in this repository:\n\n```shell\nmake\n```\n\n### Testing\n\nTo test whether the documentation is building correctly, and whether all (internal) links are correct, use:\n\n```shell\nmkdocs build --strict\n```\n\nor\n\n```shell\nmake test\n```\n\nThese commands will exit with a non-zero exit code if `mkdocs` produces any errors or warnings.\n\n### Previewing\n\nTo see a local preview of the rendered documentation in your browser, use\n\n```shell\nmkdocs serve\n```\n\nor\n\n```shell\nmake preview\n```\n\nand click the link that is provided, for example:\n\n```shell\nINFO     -  Documentation built in 0.24 seconds\nINFO     -  [17:52:07] Watching paths for changes: 'docs', 'mkdocs.yml'\nINFO     -  [17:52:07] Serving on http://127.0.0.1:8000/\n```\n\nThis preview of the rendered documentation will automatically refresh when the documentation sources are updated!\n\n### EasyBuild Framework API\n\nThe API documentation for the EasyBuild Framework is generated automatically if the EasyBuild framework code is found in ``src``:\n\n```shell\nmkdir src\ncd src\ngit clone git@github.com:easybuilders/easybuild-framework.git\n```\n\nIf the EasyBuild Framework is not found then the `mkdocs` build of the documentation will be faster, but this will cause a number of warnings messages to be printed.\n\n\n## Contributing\n\nTo contribute to the EasyBuild documentation, you should make a pull request to the `main` branch.\n\n- Fork the ``easybuild-docs`` repository to your GitHub account, clone the repository and set up a remote for your fork:\n\n   ```shell\n   git clone git@github.com:easybuilders/easybuild-docs.git\n   cd easybuild-docs\n   git add remote YOUR_GITHUB_ACCOUNT git@github.com:YOUR_GITHUB_ACCOUNT/easybuild-docs.git\n   ```\n\n- Create a branch for your changes, push it to your fork on the ``easybuild-docs`` repository, and open the pull request:\n\n  ```shell\n  vim docs/example.md\n  git checkout -b example_branch\n  git add docs/example.md\n  git commit -m \"this is just an example\"\n  git push YOUR_GITHUB_ACCOUNT example_branch\n  # create pull request in GitHub:\n  # https://github.com/YOUR_GITHUB_ACCOUNT/easybuild-docs/pull/new/example_branch\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasybuilders%2Feasybuild-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feasybuilders%2Feasybuild-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasybuilders%2Feasybuild-docs/lists"}