# HTML Report

An HTML report is generated during a [Linty scan](scan.md).
It is also available in [VS Code](https://hdl-designer.linty-services.com/).

![HTML Documentation](../assets/images/html-documentation/html-documentation.gif)

[Watch full-screen video](https://www.youtube.com/watch?v=Lm2kbTTdG8g)

## Browse

Once the Linty scan has completed, launch a simple web server (with Python for instance) to browse the report:

```
cd ${PROJET_DIRECTORY}/.linty/report/build/html/
python3 -m http.server 8001
```

Browse the report at http://localhost:8001

## Automate deployment

### On GitHub pages

On GitHub pages, at each commit on the main branch.

```yaml
name: Deploy Linty HTML Report on GitHub Pages

on:
  push:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Git Checkout
        uses: actions/checkout@v4

      - name: Run Linty Scan
        run: |
          # Replace with your current Docker command to run a Linty analysis
          docker run ...

      - name: Upload Website Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: .linty/report/build/html

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

See also [official GitHub Pages documentation](https://pages.github.com/).

Note that if you do not deploy the report to the user/organization site but to a project/repository site (such as
`https://my_org.github.io/my_repo`), you have to set the `sonar.hdl.report.urlPath` to `my_repo` for URLs to be properly
generated in the report.

```bash
docker run \
   ...
    lintyservices/linty-scanner:latest -Dsonar.hdl.report.urlPath="my_repo"
```

## Where do descriptions come from?

Any comments (either line or block comments) starting with `!` are considered as comments to be taken into account for
reporting.

For instance:

```vhdl
--! My instantiation fly08
fly08: fly
generic map (
  FLY_GENERIC => '1'
)
port map (
  ...
```

Would output:

![img.png](../assets/images/html-documentation/doxygen.png)