Ability to generate source links independent of the git repository (CI, gitlab)

[blutorange]

Search Terms

gitlab github ci pipeline source links missing repository

Problem

Before I state my problem, let me first of all say that the new documentation pages TypeDoc generates look awesome! I did not work on a frontend project for a couple of years, it's a real improvement.

I was trying to generate TypeDocs via gitlab pipelines. This works as expected, but I noticed that the source links are missing. They are generated correctly when I run TypeDoc locally. After some experimentation, I noticed that when gitlab is running pipelines, there is no .git repository, or at least not a fully initialized one. I was thinking that it should be possible to generate source links --sourceLinkTemplate and --gitRevision are provided as options, but that did not work.

For generating source links, TypeDoc seems to require at least (a) that git is installed, (b) that there exists a git repo in the workspace folder and (c) that the files are in a commit. For (a), the git command might not even exist in a CI environment.

Suggested Solution

Provided that --sourceLinkTemplate and --gitRevision are given, should it not be possible to generate source links from the path of the files alone? Perhaps a --gitRoot option might make sense, but when running in a CI environment, that will be the root folder.

Workaround

For gitlab pipelines, my current workaround is to initialize a dummy git repository and delete it afterwards

# Create gitlab pages with documentation
pages:
  stage: docs
  image: timbru31/node-alpine-git:16
  script:
    # TypeDoc does not generate source links unless there is a git repo
    - echo "Creating dummy git repo and commit for TypeDoc..."
    - rm -r .git
    - git init
    - git config user.email john.doe@example.com
    - git config user.name "John Doe"
    - git add -A
    - git commit -m dummy
    # Actual doc generation
    - echo "Generating docs for release..."
    - yarn typedoc
  after_script:
    - rm -r .git
  artifacts:
    paths:
      - public

[Gerrit0]

TypeDoc currently requires that git be installed so that it can check if a file actually exists in the git repo, rather than being .gitignored (common for types originating in node_modules, and generated code) to avoid rendering pages with broken links.

It doesn't seem completely terrible to me to have a --assumeGitRepo (or something...) flag which disables this check.

(Technically typedoc also does this so if your project is made up of multiple git repos links to each still work, but I suspect that doesn't come in to play often)

[blutorange]

common for types originating in node_modules, and generated code

We use yarn PnP, so mostly files are outside the project directory (but yarn needs to unplug some files). Although we do have generated code.

so that it can check if a file actually exists in the git repo

I see, that makes sense. This might be solved by having options such as limitToBaseDirectory or excludePatterns. But there's always a burden with having too many options, especially if it's only for one particular use case.

It doesn't seem completely terrible to me to have a --assumeGitRepo (or something...) flag which disables this check.

Yeah, sometimes having some broken links might be preferrable over having no links at all. Though having links is just a minor convenience feature.

Either way, I think it would be very helpful to add a note to the documentation to the relevant options (e.g. https://typedoc.org/options/input/#gitrevision) so that other people don't have to wonder for hours why it's not working ; ) Something like this perhaps:

Has no effect if --disableSources is set. Please note that adding source links requires that the project is a valid git project with all source files committed. If you are running in an environment without a fully initialized git folder (such as some CI environments), you might have initialize the folder first, such as via git init and/or git commit.

[Gerrit0]

I decided to go with --disableGit, which requires a sourceLinkTemplate to be set, and assumes that every file can be linked. I think I'm going to wait to add link filtering until someone runs into a use case that requires it.