Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add option to add external links to source code #1770

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

twiss
Copy link

@twiss twiss commented May 2, 2020

Q A
Bug fix? no
New feature? yes
Breaking change? no
Deprecations? no
Tests added? no
Fixed issues
License Apache-2.0

This feature is meant as a compromise between copying all source code to the documentation directory (outputSourceFiles = true), and having no links to the source code at all (outputSourceFiles = false). Instead, this option allows you to link to an external source code repository (e.g. GitHub or GitLab).

  • The templates.default.externalSourceLinks.urlPrefix option points to the location where the source code is hosted; the path of the file is appended to it.
  • The templates.default.externalSourceLinks.linenoPrefix option defaults to 'L' and refers to the L in #L5 which points to line 5 on both GitHub and GitLab.

This was manually tested against v3, not v4, because I couldn't get npm installing v4 from GitHub or a sibling directory to work. I also didn't see any tests for the outputSourceFiles feature, so I wasn't sure how to test this. All existing tests pass in v4 too, though, and the patch applied cleanly, so I imagine it should work.

Here is another example for how I intend to use this, automatically taking the repository url and version tag from package.json: https://github.com/twiss/openpgpjs/blob/v5-test/.jsdocrc.js. This should be convenient when updating the documentation whenever you release a new version, for example. That should also minimize the risk that the linked source code doesn't match the processed source code.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant