GitHub

Remote repository links

Documenterが適切に設定されている場合、公開ホストされたGitリポジトリ（例えば、GitHubにホストされたリポジトリへのソースおよび編集リンク）へのリンクを自動的に生成できます。通常、これはメインパッケージリポジトリやプロジェクトのソースコードにリンクするためのものです。

Remotes API はリモートリポジトリを指定し、URLを生成するために使用されます。また、追加のGitリポジトリホスティングサービスをサポートするために拡張できるように設計されています。

DocumenterがリモートURLを特定できるようにするために設定する必要がある（かもしれない）リモートリポジトリの2つのカテゴリがあります：

  1. プロジェクトリポジトリのリモートは、repoキーワードでmakedocsに指定されています。これは特定のファイルではなくプロジェクト全体を指し、リポジトリのランディングページリンク、イシューの参照などに使用されます。

  2. ファイルリンクリモートは、remotesキーワードによってmakedocsに指定されます。これらは、ファイルシステムのファイルをリモートリポジトリ内の対応するファイルにリンクするために使用されます。特に、これらはマニュアルページの編集リンクや、ドキュメント文字列のためのJuliaソースファイルリンクを生成するために使用されます。

最も一般的なケース、つまりシンプルなJuliaパッケージのリポジトリの場合、通常はリンクするリモートリポジトリが1つだけであり、ファイルリンクとリポジトリリンクの区別は重要ではありません。しかし、より複雑なセットアップでは、2つのケースを区別する必要があるかもしれません。デフォルトの2つのキーワードは、最も一般的な使用ケースに対応するように設計されており、as is explained below、これはこれら2つの引数の間に何らかの相互作用が必要であることを意味します。

Remotes for files

Documenterがホストされたリポジトリ内のファイルのURLを決定する必要がある場合、ローカルファイルシステムの絶対パスを入力として受け取ります。[1] Markdownファイルの場合、これらのローカルパスはmakedocsによって決定されます。Juliaファイルへのリンクはドキュメントシステムから決定され、コードが読み込まれた場所を指します（例えば、環境の開発依存関係の場合、これらはPkg.developされたパスから来ますが、通常のPkg.add依存関係の場合、ソースファイルは通常~/.julia/packagesにあります）。

ほとんどの場合、MarkdownおよびJuliaファイルに関して、Documenterが関心を持つファイルは、Documenter make.jl スクリプトを含む現在チェックアウトされているGitリポジトリにあります（例：ローカルにチェックアウトされたパッケージリポジトリ）。しかし、場合によっては、異なるリポジトリ（プライマリリポジトリのサブディレクトリ内または外部）にあることもありますし、プライマリリポジトリの外部にある非Gitディレクトリにあることもあります（例：リリースタールボールのドキュメントをビルドしようとしている場合）。

そのようなケースを処理するために、remotes キーワードを makedocs に使用して、ローカルファイルシステムパスのための local directory => remote repository マッピングを設定できます。ローカルディレクトリはGitリポジトリのルートに対応していると仮定され、そのディレクトリ内の任意のサブパスはリモートリポジトリ内の対応するパスに解決されます。ネストされた remotes が設定されている場合、Documenterは元のパスからディレクトリツリーを上に移動しながら最初に一致するものを使用します。

一般的なケースは、ローカルでチェックアウトされたGitリポジトリ（Pkg.developを使用してドキュメント環境に追加されたもの）や、GitHubにホストされているリリースパッケージ（環境にPkg.addされたもの）です。Documenterは、これらのリモートを自動的に特定しようとします。

  • Documenterがディレクトリツリーを上がると、ディレクトリがGitリポジトリのルートであるかどうかを確認します（.gitディレクトリまたはファイルの存在を探します）。有効なローカルリポジトリのルートを見つけると、それのorigin remote URLを読み取ろうとします。
    • そのディレクトリがGitHubリポジトリ[2]と一致する場合、Documenterは自動的にそのディレクトリからのマッピングを設定し、それを使用してリモートURLを決定します。
    • Documenterがリポジトリのoriginからリモートを特定できない場合（例えば、originが設定されていない、または他の場所にホストされている場合）、リモートURLを特定できないためエラーが発生します。この場合、リモートはremotesを使用して明示的に設定する必要があります。

それを、Documenterが見つけたクローンされたGitHubリポジトリでremotesを自動的に埋めると考えることができます。[3]

リリースされたパッケージ（Pkg.add(...)を使用して追加されたもので、Pkg.develop(...)ではないもの）については、バージョンとリポジトリはパッケージメタデータから判断できますが、コミットハッシュは簡単には入手できません。この場合、Documenterはリポジトリにv$VERSIONというタグが存在すると推測します。これらのタグは、広く使用されているJuliaRegistries/TagBotアクションによって自動的に作成されることに注意してください。これは時々そうでない場合があり、死んだリンクや不正確なリンクを引き起こす可能性があるため、linkcheckキーワードをtrueに設定すると、makedocsは、これらの推測されたリンクが既存のターゲットを持っているか、既存のターゲットが公開されたパッケージと一致するかを確認します。（これは、ドキュメントからの他のすべての外部リンクにも影響します。）このオプションを有効にすると、ネットワークエラーや外部サービスの一時的なダウンタイムのためにドキュメントビルドが失敗する可能性があることに注意してください。

Note

Remotes APIを使用して、リモートURLを計算するメソッドを実装できます（現時点では、DocumenterはGitHubとGitLabをネイティブにサポートしています）。

repo & remotes interaction

Documenterは主にJuliaパッケージのドキュメントを生成するために使用されるため、repoとremotesキーワード引数の間には自動的にデフォルトを決定するための相互作用があります。これは通常、make.jlスクリプト内でどちらかを明示的に指定する必要がないことを意味します。

ルールは次のとおりです：

  • repo が指定されていない場合、基本的には determined like any other remote link になります。これは、makedocs の root パス引数を含むリポジトリを特定しようとすることによって得られます（デフォルトでは make.jl スクリプトのディレクトリ、通常は docs/ ディレクトリ）。Remote オブジェクトは remotes の一つであり、これは含まれる Git リポジトリの origin URL を介して自動的に決定されている可能性があります。

  • repo が指定されているが、リポジトリルートの remotes が指定されていない場合、repo はリポジトリルートの remotes エントリとして機能します。これは、同じ引数を二度指定する必要がないようにするためです（すなわち、一般的なリポジトリリンク用とファイルリンク用の二度）。

  • repoとリポジトリルートのremotesの両方が設定されている場合、Documenterはエラーをスローします。なぜなら、それらが2つの異なるリモートを指すことは実際には意味がないからです。[4]

Remotes API

Documenter.Remotes.GitHub — Type
GitHub(user :: AbstractString, repo :: AbstractString)
GitHub(remote :: AbstractString)

Represents a remote Git repository hosted on GitHub. The repository is identified by the names of the user (or organization) and the repository: GitHub(user, repository). E.g.:

makedocs(
    repo = GitHub("JuliaDocs", "Documenter.jl")
)

The single-argument constructor assumes that the user and repository parts are separated by a slash (e.g. JuliaDocs/Documenter.jl).

source
Documenter.Remotes.GitLab — Type
GitLab(host, user, repo)
GitLab(user, repo)
GitLab(remote)

Represents a remote Git repository hosted on GitLab. The repository is identified by the host, name of the user (or organization), and the repository. For example:

makedocs(
    repo = GitLab("JuliaDocs", "Documenter.jl")
)

The single argument constructor assumes that the end user and repository parts are separated by a slash (e.g., JuliaDocs/Documenter.jl).

source

次の型と関数は、カスタム Remote 型を作成する際に関連しています：

Documenter.Remotes.Remote — Type
abstract type Remote

Abstract supertype for implementing additional remote repositories that Documenter can use when generating links to files hosted on Git hosting service (such as GitHub, GitLab etc). For custom or less common Git hosting services, the user can create their own Remote subtype and pass that as the repo argument to makedocs.

When implementing a new type T <: Remote, the following functions must be extended for that type:

Additionally, it may also extend the following functions:

source
Documenter.Remotes.repourl — Function
Remotes.repourl(remote::T) -> String

An internal Documenter function that must be extended when implementing a user-defined Remote. It should return a string pointing to the landing page of the remote repository. E.g. for GitHub it returns "https://github.com/USER/REPO/".

source
Documenter.Remotes.fileurl — Function
Remotes.fileurl(remote::T, ref, filename, linerange) -> String

An internal Documenter function that must be extended when implementing a user-defined Remote. Should return the full remote URL to the source file filename, optionally including the line numbers.

  • ref is string containing the Git reference, such as a commit SHA, branch name or a tag name.

  • filename is a string containing the full path of the file in the repository without any leading / characters.

  • linerange either specifies a range of integers or is nothing. In the former case it either specifies a line number (if first(linerange) == last(linerange)) or a range of lines (first(linerange) < last(linerange)). The line information should be accessed only with the first and last functions (no other interface guarantees are made).

    If linerange is nothing, the line numbers should be omitted and the returned URL should refer to the full file.

    It is also acceptable for an implementation to completely ignore the value of the linerange argument, e.g. when the remote repository does not support direct links to particular line numbers.

E.g. for GitHub, depending on the input arguments, it would return the following strings:

reffilenamelinerangereturned string
"master""foo/bar.jl"nothing"https://github.com/USER/REPO/blob/master/foo/bar.jl"
"v1.2.3""foo/bar.jl"12:12"https://github.com/USER/REPO/blob/v1.2.3/foo/bar.jl#L12"
"xyz/foo""README.md"10:15"https://github.com/USER/REPO/blob/xyz/foo/README.md#L10-L15"
source
Documenter.Remotes.issueurl — Function
Remotes.issueurl(remote::T, issuenumber)

An internal Documenter function that can be extended when implementing a user-defined Remote. It should return a string with the full URL to an issue referenced by issuenumber, or nothing if it is not possible to determine such a URL.

  • issuenumber is a string containing the issue number.

It is not mandatory to define this method for a custom Remote. In this case it just falls back to always returning nothing.

E.g. for GitHub when issuenumber = "123", it would return "https://github.com/USER/REPO/issues/123".

source
  • 1There is an exception to this: links to Julia Base module source files. But Documenter already known how to handle those correctly, and they are really only relevant to the Julia main manual build.
  • 2GitHub is the most common case, but this could be extended to cover other Git hosting services in the future (as long as the remote can reliably determined from the origin URL).
  • 3One thing to be aware here is that Documenter builds up a cache of the Git repositories it finds on every makedocs call. This is for performance reasons, to reduce the number of file system accesses and, in particular, git calls, which are relatively slow.
  • 4If there is a use case for this, this limitation could be relaxed in the future.