Declare stable API

JuliaDocs · Jun 7, 2024 · cf27ebe · cf27ebe
1 parent 9f1f60f
commit cf27ebe
Show file tree

Hide file tree

Showing 4 changed files with 17 additions and 5 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,4 @@
+# Release Notes
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "DocumenterInterLinks"
 uuid = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 authors = ["Michael Goerz <mail@michaelgoerz.net>"]
-version = "0.3.3"
+version = "1.0.0-dev"
 
 [deps]
 CodecZlib = "944b1d66-785c-5afd-91f1-9de20f533193"

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -30,7 +30,7 @@ end
 [DocumenterInterLinks.jl](https://github.com/JuliaDocs/DocumenterInterLinks.jl#readme) is a plugin for [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) to link to external projects. It is interoperable with [Intersphinx](@extref sphinx :doc:`usage/extensions/intersphinx`) for Python projects.
 
 
-## Installation Instructions
+## Installation
 
 
 As usual, the package can be installed via
@@ -146,3 +146,8 @@ We can include the domain and role in an `@extref` link as
 ```
 
 using a [syntax](@ref Syntax) that is reminiscent of the [Sphinx cross-referencing syntax](@extref sphinx xref-syntax). The use of domains and roles in `DocumenterInterLinks` ([unlike in Sphinx](@ref Compatibility-with-Sphinx)) is for disambiguation only, in case there are multiple items with the same `name`. In general, follow the [Recommended Syntax](@ref) guidelines.
+
+
+## Public API and Changelog
+
+The `DocumenterInterLinks` project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). See the [`CHANGELOG`](https://github.com/JuliaDocs/DocumenterInterLinks.jl/blob/master/CHANGELOG.md) for changes after `v1.0`. The "public API" extends to the documented `@extref` [Syntax](@ref) and to the instantiation of the [`InterLinks`](@ref) plugin. Other [Internals](@ref) or features marked as "experimental" may change in minor versions.
diff --git a/src/interlinks.jl b/src/interlinks.jl
@@ -7,7 +7,7 @@ Plugin for enabling external links in `Documenter.jl.`
 
 ```julia
 links = InterLinks(
-    mapping;
+    mappings...;
     default_inventory_file="objects.inv",
     alias_methods_as_function=true,
 )
@@ -16,7 +16,7 @@ links = InterLinks(
 instantiates a plugin object that must be passed as an element of the `plugins`
 keyword argument to [`Documenter.makedocs`](@extref). This then
 enables `@extref` links in the project's documentation to be resolved, see the
-[Syntax](@ref) documentation for details. The `mapping` connects project names
+[Syntax](@ref) documentation for details. The `mappings` connect project names
 to project root URLs and inventories, e.g.,
 
 ```julia
@@ -68,10 +68,13 @@ any of the following forms (from most common to least common):
 
 # Keyword arguments
 
+The keyword arguments to `InterLinks` are experimental and may change in minor
+versions.
+
 * `default_inventory_file`: The file name for the inventory file to use if the
   "inventory location" is given as the root URL. Since both Sphinx and
   Documenter automatically write `objects.inv`, there is little conceivable
-  reason to set this to something other than the default `objects.inv`.
+  reason to set this to something other than the default `"objects.inv"`.
 * `alias_methods_as_function`: If `true` (default), for any inventory loaded
   from a file or URL, automatically add a `:jl:function:` alias for any
   `:jl:method` if that alias is unambiguous. This accounts for Documenter