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

Update docs per rebar3_hex v7 release #1098

Merged
merged 6 commits into from Jan 3, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
4 changes: 2 additions & 2 deletions lib/hexpm_web/templates/docs/rebar3_private.html.md
Expand Up @@ -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
Expand All @@ -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 <key>
$ rebar3 hex organization auth hexpm:private_org -k <key>
```

This can then be used to fetch packages on your CI servers without requiring manual authentication with username and password.
36 changes: 34 additions & 2 deletions lib/hexpm_web/templates/docs/rebar3_publish.html.md
Expand Up @@ -57,8 +57,15 @@ You can also add any of the following to the list of application attributes:
<dd>A map where the key is a link name and the value is the link URL. Optional but highly recommended.</dd>
<dt><code>files</code></dt>
<dd>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.</dd>
<dt><code>include_paths</code></dt>
<dd>A list of paths containing files you wish to include in a release.</dd>
<dt><code>exclude_paths</code></dt>
<dd>A list of paths containing files you wish to exclude in a release.</dd>
starbelly marked this conversation as resolved.
Show resolved Hide resolved
<dt><code>exclude_patterns</code></dt>
<dd>A list of regular expressions used to exclude files that may have been accumulated via files and include_paths and standard project paths.</dd>
<dt><code>build_tools</code></dt>
<dd>List of build tools that can build the package. It's very rare that you need to set this.</dd>

starbelly marked this conversation as resolved.
Show resolved Hide resolved
</dl>

#### Dependencies
Expand Down Expand Up @@ -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/).


starbelly marked this conversation as resolved.
Show resolved Hide resolved
```erlang
ex_doc, [
starbelly marked this conversation as resolved.
Show resolved Hide resolved
{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 :
starbelly marked this conversation as resolved.
Show resolved Hide resolved

```erlang
{hex, [{doc, edoc}]}.
```

### Submitting the package

After the package metadata and dependencies have been added to `src/<myapp>.app.src`, we are ready to publish the package with the `rebar3 hex publish` command:
Expand Down Expand Up @@ -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.
Expand All @@ -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.