From a0281f57696371b7ac543bf1cc42a9fc1bd91422 Mon Sep 17 00:00:00 2001 From: Bryan Paxton Date: Fri, 31 Dec 2021 17:52:09 -0600 Subject: [PATCH 1/6] Update docs per v7.0.0 release --- .../templates/docs/rebar3_private.html.md | 4 +-- .../templates/docs/rebar3_publish.html.md | 36 +++++++++++++++++-- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/lib/hexpm_web/templates/docs/rebar3_private.html.md b/lib/hexpm_web/templates/docs/rebar3_private.html.md index d9270362f..453a6f7d1 100644 --- a/lib/hexpm_web/templates/docs/rebar3_private.html.md +++ b/lib/hexpm_web/templates/docs/rebar3_private.html.md @@ -8,7 +8,7 @@ This allows the same mechanism to be used for both mirrors, private repositories ### Publishing or using a private package -For publishing or using a private repository you must use the [rebar3_hex](https://github.com/tsloughter/rebar3_hex) plugin to authenticate, `rebar3 hex auth` after declaring the private organization (defined as `parent_repo:organization`, see the example is below) as a repository in the rebar3 config. Authenticating then creates a separate config file `~/.config/rebar3/hex.config` storing the keys. +For publishing or using a private repository you must use the [rebar3_hex](https://github.com/erlef/rebar3_hex) plugin to authenticate, `rebar3 hex organization auth` after declaring the private organization (defined as `parent_repo:organization`, see the example is below) as a repository in the rebar3 config. Authenticating then creates a separate config file `~/.config/rebar3/hex.config` storing the keys. ```erlang @@ -24,7 +24,7 @@ To publish to a private repository, use `rebar3 hex publish -r hexpm:private_org You can generate organizations keys on your organization's [dashboard](/dashboard). ```nohighlight -$ rebar3 hex repo auth private_org -k +$ rebar3 hex organization auth hexpm:private_org -k ``` This can then be used to fetch packages on your CI servers without requiring manual authentication with username and password. diff --git a/lib/hexpm_web/templates/docs/rebar3_publish.html.md b/lib/hexpm_web/templates/docs/rebar3_publish.html.md index 0784b0a45..e42a2c024 100644 --- a/lib/hexpm_web/templates/docs/rebar3_publish.html.md +++ b/lib/hexpm_web/templates/docs/rebar3_publish.html.md @@ -57,8 +57,15 @@ You can also add any of the following to the list of application attributes:
A map where the key is a link name and the value is the link URL. Optional but highly recommended.
files
A list of files and directories to include in the package. Defaults to standard project directories, so you usually don't need to set this property.
+
include_paths
+
A list of paths containing files you wish to include in a release.
+
exclude_paths
+
A list of paths containing files you wish to exclude in a release.
+
exclude_patterns
+
A list of regular expressions used to exclude files that may have been accumulated via files and include_paths and standard project paths.
build_tools
List of build tools that can build the package. It's very rare that you need to set this.
+ #### Dependencies @@ -101,6 +108,29 @@ Only Hex packages may be used as dependencies of the package. It is not possible ``` +#### Documentation + +rebar3_hex by default expects you to configure a documentation provider. We recommend using +[rebar3_ex_doc](https://hexdocs.pm/rebar3_ex_doc/) for publishing documentation along with your package for a consistent +format and style on [hex.pm](https://hex.pm/). + + +```erlang +ex_doc, [ + {source_url, <<"https://github.com/namespace/your_app">>}, + {extras, [<<"README.md">>, <<"LICENSE">>]}, + {main, <<"readme">>} +]}. + +{hex, [{doc, ex_doc}]}. +``` + +Alternatively, or on Erlang versions older than OTP-24, you can use the edoc provider that ships with rebar3 : + +```erlang +{hex, [{doc, edoc}]}. +``` + ### Submitting the package After the package metadata and dependencies have been added to `src/.app.src`, we are ready to publish the package with the `rebar3 hex publish` command: @@ -130,7 +160,9 @@ Publishing relx 3.5.0 LICENSE.md Proceed? ("Y") Y Published relx 3.5.0 - +Running edoc for relx +Running ex_doc for relx +Published docs for relx 3.5.0 ``` Congratulations, you've published your package! It will appear on the [https://hex.pm](https://hex.pm/) site and will be available to add as a dependency in other rebar3 or mix projects. @@ -139,4 +171,4 @@ Please test your package after publishing by adding it as dependency to a rebar3 When running the command to publish a package, Hex will create a tar file of all the files and directories listed in the `files` property. When the tarball has been pushed to the Hex servers, it will be uploaded to a CDN for fast and reliable access for users. Hex will also recompile the registry file that all clients will update automatically when fetching dependencies. -The [rebar3 hex plugin's documentation](https://rebar3.org/docs/package_management/hex_package_management/) contains more information about the hex plugin itself and publishing packages. +The [rebar3 hex plugin's documentation](https://hexdocs.pm/rebar3_hex/) contains more information about the hex plugin itself and publishing packages. From f81debdc40ba99f5c1c5663c937fa8be43a8e480 Mon Sep 17 00:00:00 2001 From: Bryan Paxton <39971740+starbelly@users.noreply.github.com> Date: Sun, 2 Jan 2022 18:00:54 -0600 Subject: [PATCH 2/6] Update lib/hexpm_web/templates/docs/rebar3_publish.html.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Eric Meadows-Jönsson --- lib/hexpm_web/templates/docs/rebar3_publish.html.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/hexpm_web/templates/docs/rebar3_publish.html.md b/lib/hexpm_web/templates/docs/rebar3_publish.html.md index e42a2c024..50853f2cd 100644 --- a/lib/hexpm_web/templates/docs/rebar3_publish.html.md +++ b/lib/hexpm_web/templates/docs/rebar3_publish.html.md @@ -58,9 +58,9 @@ You can also add any of the following to the list of application attributes:
files
A list of files and directories to include in the package. Defaults to standard project directories, so you usually don't need to set this property.
include_paths
-
A list of paths containing files you wish to include in a release.
+
A list of paths containing files you wish to include in the package.
exclude_paths
-
A list of paths containing files you wish to exclude in a release.
+
A list of paths containing files you wish to exclude in the package.
exclude_patterns
A list of regular expressions used to exclude files that may have been accumulated via files and include_paths and standard project paths.
build_tools
From 6402c89b81fe914e26d1bd794aaa3473a5697d60 Mon Sep 17 00:00:00 2001 From: Bryan Paxton <39971740+starbelly@users.noreply.github.com> Date: Sun, 2 Jan 2022 18:01:00 -0600 Subject: [PATCH 3/6] Update lib/hexpm_web/templates/docs/rebar3_publish.html.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Eric Meadows-Jönsson --- lib/hexpm_web/templates/docs/rebar3_publish.html.md | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/hexpm_web/templates/docs/rebar3_publish.html.md b/lib/hexpm_web/templates/docs/rebar3_publish.html.md index 50853f2cd..b9e97db32 100644 --- a/lib/hexpm_web/templates/docs/rebar3_publish.html.md +++ b/lib/hexpm_web/templates/docs/rebar3_publish.html.md @@ -114,7 +114,6 @@ rebar3_hex by default expects you to configure a documentation provider. We reco [rebar3_ex_doc](https://hexdocs.pm/rebar3_ex_doc/) for publishing documentation along with your package for a consistent format and style on [hex.pm](https://hex.pm/). - ```erlang ex_doc, [ {source_url, <<"https://github.com/namespace/your_app">>}, From f6d4f2f285f2be94f12ccfa1be4b5edd989f7faa Mon Sep 17 00:00:00 2001 From: Bryan Paxton <39971740+starbelly@users.noreply.github.com> Date: Sun, 2 Jan 2022 18:01:06 -0600 Subject: [PATCH 4/6] Update lib/hexpm_web/templates/docs/rebar3_publish.html.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Eric Meadows-Jönsson --- lib/hexpm_web/templates/docs/rebar3_publish.html.md | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/hexpm_web/templates/docs/rebar3_publish.html.md b/lib/hexpm_web/templates/docs/rebar3_publish.html.md index b9e97db32..cc1b53c63 100644 --- a/lib/hexpm_web/templates/docs/rebar3_publish.html.md +++ b/lib/hexpm_web/templates/docs/rebar3_publish.html.md @@ -65,7 +65,6 @@ You can also add any of the following to the list of application attributes:
A list of regular expressions used to exclude files that may have been accumulated via files and include_paths and standard project paths.
build_tools
List of build tools that can build the package. It's very rare that you need to set this.
- #### Dependencies From d62ac9511eff2d2bc76f4ccf632993eff10265aa Mon Sep 17 00:00:00 2001 From: Bryan Paxton <39971740+starbelly@users.noreply.github.com> Date: Sun, 2 Jan 2022 18:01:12 -0600 Subject: [PATCH 5/6] Update lib/hexpm_web/templates/docs/rebar3_publish.html.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Eric Meadows-Jönsson --- lib/hexpm_web/templates/docs/rebar3_publish.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/hexpm_web/templates/docs/rebar3_publish.html.md b/lib/hexpm_web/templates/docs/rebar3_publish.html.md index cc1b53c63..d38aedff4 100644 --- a/lib/hexpm_web/templates/docs/rebar3_publish.html.md +++ b/lib/hexpm_web/templates/docs/rebar3_publish.html.md @@ -114,7 +114,7 @@ rebar3_hex by default expects you to configure a documentation provider. We reco format and style on [hex.pm](https://hex.pm/). ```erlang -ex_doc, [ +{ex_doc, [ {source_url, <<"https://github.com/namespace/your_app">>}, {extras, [<<"README.md">>, <<"LICENSE">>]}, {main, <<"readme">>} From 69505fcbf7203b546839fccc727ca3b343b68aad Mon Sep 17 00:00:00 2001 From: Bryan Paxton <39971740+starbelly@users.noreply.github.com> Date: Sun, 2 Jan 2022 18:01:17 -0600 Subject: [PATCH 6/6] Update lib/hexpm_web/templates/docs/rebar3_publish.html.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Eric Meadows-Jönsson --- lib/hexpm_web/templates/docs/rebar3_publish.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/hexpm_web/templates/docs/rebar3_publish.html.md b/lib/hexpm_web/templates/docs/rebar3_publish.html.md index d38aedff4..76713b266 100644 --- a/lib/hexpm_web/templates/docs/rebar3_publish.html.md +++ b/lib/hexpm_web/templates/docs/rebar3_publish.html.md @@ -123,7 +123,7 @@ format and style on [hex.pm](https://hex.pm/). {hex, [{doc, ex_doc}]}. ``` -Alternatively, or on Erlang versions older than OTP-24, you can use the edoc provider that ships with rebar3 : +Alternatively, or on Erlang versions older than OTP-24, you can use the edoc provider that ships with rebar3: ```erlang {hex, [{doc, edoc}]}.