hylo-lang / hylodoc Goto Github PK

View Code? Open in Web Editor NEW

0.0 1.0 0.0 1012 KB

Code documentation generator for Hylo

Home Page: https://hylodoc.web.app

License: Apache License 2.0

Dockerfile 0.51% Shell 0.38% Swift 88.44% C 0.06% HTML 6.77% JavaScript 0.33% SCSS 2.58% TypeScript 0.94%

documentation documentation-generator

hylodoc's Introduction

HyloDoc - Automatic Documentation Generation Tool

Getting Started

To use HyloDoc for generating websites, you can use its command line interface or use it as a library in your project to gain more control and customization.

After setting up the development environment, you can run the HyloDoc CLI the following command:

swift run -c release hdc

The 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.

hdc --help

# Outputs documentation of one module to ./dist
hdc PATH_TO_MODULE

# Process multiple modules
hdc PATH_TO_MODULE_1 PATH_TO_MODULE_2 ...

# Specify output directory
hdc PATH_TO_MODULE --output OUTPUT_DIRECTORY

# Preview the generated website by starting a web server
hdc PATH_TO_MODULE && python3 -m http.server 8080 -d dist

# Generate documentation for the Standard Library
hdc ./Sources/StandardLibrary/Sources -s

# Preview the website after generating
hdc ./Sources/StandardLibrary/Sources -s --preview

Documentation Syntax Reference

You can read our syntax specification in the Syntax Reference

Development Environment Setup

Windows

Install docker and WSL2
Clone the repo into a WSL folder
Open the repo in Windows VSCode, reopen it in devcontainer

Debugging and Running Tests

Once you open up a devcontainer, there should be a run configuration called "Debug Tests" in the run and debug tab.
Additionally, you should be able to debug individual tests cases and test methods by clicking on the green arrow next to them. If you right-click the arrow, you will have the option to debug the particular test.

Mac

Set up Swift 5.10 and LLVM, according to the Hylo compiler's repository
CLone the repository

Running the Tests

To run all tests, you can use the following command:

swift test

Alternatively, in VSCode after the first full build of the project, you should be able to see green arrows next to the test cases, which you can click to run them individually, and to debug them.

Formatting

This project uses the swift-format library to enforce good formatting of all .swift files. There is a job in the pipeline that will fail if the library finds any lines of code that do not conform to the ruleset .swift-format.json. To check if your staged files adhere to this standard you can run the following command in the devcontainer terminal:

swift-format lint -r --configuration .swift-format.json -p Sources Tests Package.swift

If there are any problems, you one can run this command to fix most errors in all files.

./format-all.sh

You 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.

However, there are some limitations to these formatting tools that will still fail the pipeline, which will require manual modifications.

Pre-commit git hook

There 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.

To 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:

git clone -b release/5.10 https://github.com/apple/swift-format.git && cd swift-format && swift build -c release && export PATH="$(pwd)/.build/release:$PATH" && swift-format --version

This 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.

Finally, add the pre-commit script to your .git folder. Copy pre-commit from the project root and paste it in .git/hooks.

hylodoc's People

Contributors

Watchers

hylodoc's Issues

Expand visited navigation tree items

Just like in vscode, if you navigate to a specific file through a link, the navigation tree should automatically expand from the root until the given target.

The tree navigation UX is very much open for discussion, so if you have an interesting idea, feel free to incorporate it.

web

Using RelativePath and AbsolutePath instead of Swift's URL types

Swift URLs can refer to relative paths, absolute paths, might or might not contain / at the end of the path, so in general the type does not have much guarantees when working with. This makes working with them in the website generation quite error-prone and it's hard to reason about the type of URL received as an argument without keeping the whole website generation code base in our head.

We should use some ideas from https://github.com/sersoft-gmbh/path-wrangler, along with new nominal types for different purposes, e.g. absolute path on disk vs absolute path for a web url.

This could save us from many calls from url.standardized that we sometimes use throughout the code base to be sure that we don't have weird things going on in the URL, and we can compare them part-wise to e.g. determine when one url subsumes another one.

Add # Projects for subscripts and computed properties in syntax reference

Update https://github.com/hylo-lang/hylodoc/blob/dev/SyntaxReference.md to include the # Projects: special section.

Migrate all remaining issues from GitLab

There are many Issues left in the repository from our university project. We need to migrate these here, and write a description for (most of them) that is suitable for new contributors.

Verify and improve accessibility of the project for new contributors

The presence of proper documentation and onboarding for each of the different components (e.g. Swift modules and web design) should be checked to verify if the hylodoc project is accessible to new contributors. This is important for keeping the project maintainable in the long run.

Convert inline code references to use double backticks in the standard library

We have already converted the standard library to use our new syntax for special sections inside https://github.com/hylo-lang/hylodoc/tree/dev/Sources/StandardLibrary/Sources

Hylo code references are still not updated though, so there are still places where `myFunction(_:)` is written instead of ``myFunction(_:)``.

Updating the standard library to use this syntax would make the references be checked when generating the documentation, so it would be harder to accidentally making documentation obsolete when doing some refactoring.

For the details of the syntax, see https://github.com/hylo-lang/hylodoc/blob/dev/SyntaxReference.md#symbol-references

Only export public declarations into the website

Currently, there is no filtering for symbols in the website generation. Readers are only interested in declarations that they can use from outside the module, so we should filter for public declarations. Refer to https://github.com/hylo-lang/specification/blob/main/spec.md#modifiers for details.

Relevant files from Hylo frontend: AccessModifier.swift, all files within Frontend/AST/Decl.
Relevant folder from HyloDoc: Sources/WebsiteGen/

Migrate website generation from Stencil templates to Plot DSL

The current approach for website generation is to use an html templating library Stencil. This proved to be very error-prone to work with, and it's also unbearably slow for large number of templates. When using it, we use all Swift's type safety, guarantees and compile-time optimizations, making the experience similar to a dynamic language.

We should experiment with switching the website generation to be done fully in Swift, and see what it would unlock performance wise.

Add option to deploy to subfolders

Currently, the website generation assumes the project will be deployed to a domain's root. However, many people want to host their documentation in a subfolder, like https://example.com/docs, in which case all our absolute references would break, e.g. src="/assets/style.css".

There are multiple solutions:

Adding support for setting a base url in the CLI, and use html's meta base tag to define the base url. After that, all relative urls would be resolved from that base, probably also inside css files.
Outputting relative urls everywhere, that correctly reference the targets. This requires computing the relative urls from every html file to every target that is being referred to, and the css references would probably not work unless we generate the parts of the css inside the html that are referencing assets (e.g. background: url(../../../assets/icons/copy.svg). This would be very convenient from the user side, as they wouldn't need to worry about setting base urls, they could even open up the website from their file browser without the need for a web server. It would only be possible to do after we have migrated away from Stencil, the html templating library that we are using, because if we need to regenerate the navigation side panel for all html files, it takes over 2 minutes to export documentation for the standard library.

Flatten documentation root for single-module documentation

Currently every documentation website includes an index page which functions as the root of the documentation listing all documented modules and providing a nice entry into them. For single-module documentation it would however be prefered to not have this index and rather step into the single module directly. This results in a nicer user experience as it skips an unnecessary step in navigating the documentation.

The expected behaviour would be:

In case of multiple modules keep the index page and navigation tree as is.
In case of a single module flatten the documentation to have the only module be the root.