{"id":15169033,"url":"https://github.com/hylo-lang/hylodoc","last_synced_at":"2026-04-10T21:46:06.888Z","repository":{"id":251111998,"uuid":"820074677","full_name":"hylo-lang/hylodoc","owner":"hylo-lang","description":"Code documentation generator for Hylo","archived":false,"fork":false,"pushed_at":"2024-08-31T18:31:04.000Z","size":6003,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-01-12T15:45:31.799Z","etag":null,"topics":["documentation","documentation-generator"],"latest_commit_sha":null,"homepage":"https://hylodoc.web.app","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hylo-lang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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":"2024-06-25T18:40:59.000Z","updated_at":"2024-09-17T00:16:56.000Z","dependencies_parsed_at":"2025-01-12T15:42:50.573Z","dependency_job_id":"5dd3bcc6-2e4e-4067-9c1f-22584d6aa514","html_url":"https://github.com/hylo-lang/hylodoc","commit_stats":null,"previous_names":["hylo-lang/hylodoc"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hylo-lang%2Fhylodoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hylo-lang%2Fhylodoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hylo-lang%2Fhylodoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hylo-lang%2Fhylodoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hylo-lang","download_url":"https://codeload.github.com/hylo-lang/hylodoc/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241451666,"owners_count":19964901,"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","documentation-generator"],"created_at":"2024-09-27T07:00:47.747Z","updated_at":"2026-04-10T21:46:01.830Z","avatar_url":"https://github.com/hylo-lang.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"# HyloDoc - Documentation Compiler for Hylo\n\n\u003e This project started as a university project. The project's [Final Report](./project-report.pdf) presents academic research and industry practices around documentation, and details HyloDoc's design, implementation and plans for future development.\n\n## Getting Started\nTo use HyloDoc for generating websites, you can use its command line interface or use it as a library in your project\nto gain more control and customization.\n\nAfter setting up the development environment, you can run the HyloDoc CLI the following command:\n```shell\nswift run -c release hdc\n```\n\nThe CLI can extract documentation from one or more folders and generate a website into the output directory, which by default is `./dist`. An http server can be started after generation by the `--preview` flag.\n\n```shell\nhdc --help\n\n# Outputs documentation of one module to ./dist\nhdc PATH_TO_MODULE\n\n# Process multiple modules\nhdc PATH_TO_MODULE_1 PATH_TO_MODULE_2 ...\n\n# Specify output directory\nhdc PATH_TO_MODULE --output OUTPUT_DIRECTORY\n\n# Preview the generated website by starting a web server\nhdc PATH_TO_MODULE \u0026\u0026 python3 -m http.server 8080 -d dist\n\n# Generate documentation for the Standard Library\nhdc ./Sources/StandardLibrary/Sources -s\n\n# Preview the website after generating\nhdc ./Sources/StandardLibrary/Sources -s --preview\n```\n\n## Documentation Syntax Reference\nYou can read our syntax specification in the [Syntax Reference](./SyntaxReference.md)\n## Development Environment Setup\n### Windows\n- Install docker and WSL2\n- Clone the repo into a WSL folder\n- Open the repo in Windows VSCode, reopen it in devcontainer\n\n#### Debugging and Running Tests\n- Once you open up a devcontainer, there should be a run configuration called \"Debug Tests\" in the run and debug tab.\n- Additionally, you should be able to debug individual tests cases and test methods by clicking on the green arrow next \n  to them. If you right-click the arrow, you will have the option to debug the particular test.\n\n### Mac\n- Set up Swift 5.10 and LLVM, according to the [Hylo compiler's repository](https://github.com/hylo-lang/hylo)\n- CLone the repository\n\n## Running the Tests\nTo run all tests, you can use the following command:\n```shell\nswift test\n```\nAlternatively, in VSCode after the first full build of the project, you should be able to see green arrows next to the \ntest cases, which you can click to run them individually, and to debug them.\n\n### Formatting\n\nThis project uses the `swift-format` library to enforce good formatting of all `.swift` files. There is a job in the \npipeline that will fail if the library finds any lines of code that do not conform to the ruleset `.swift-format.json`.\nTo check if your staged files adhere to this standard you can run the following command in the devcontainer terminal:\n\n```\nswift-format lint -r --configuration .swift-format.json -p Sources Tests Package.swift\n```\n\nIf there are any problems, you one can run this command to fix *most* errors in all files.\n```\n./format-all.sh\n```\nYou can alternatively use the VSCode extension `vknabel.vscode-apple-swift-format` and the `Shift + Alt + F` shortcut for formatting the current file. Note that it takes some time until the library initializes itself in a devcontainer.\n\nHowever, there are some limitations to these formatting tools that will still fail the pipeline, which will require manual modifications.\n\n#### Pre-commit git hook\n\nThere is a pre-commit git hook that will run the format command on any staged `.swift` files. It is provided as `pre-commit` in the project root.\n\nTo use it, you need to have Swift 5.10 installed and available in the PATH environment variable. Next, install the `swift-format` library locally and add it to `$PATH`. Navigate to a suitable location and run the following command:\n\n```\ngit clone -b release/5.10 https://github.com/apple/swift-format.git \u0026\u0026 cd swift-format \u0026\u0026 swift build -c release \u0026\u0026 export PATH=\"$(pwd)/.build/release:$PATH\" \u0026\u0026 swift-format --version\n```\n\nThis will clone and build the required `swift-format` version and add it to your PATH. If the installation has been successful, the terminal output should read `508.0.0`.\n\nFinally, add the pre-commit script to your `.git` folder. Copy `pre-commit` from the project root and paste it in `.git/hooks`. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhylo-lang%2Fhylodoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhylo-lang%2Fhylodoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhylo-lang%2Fhylodoc/lists"}