Release docs for non-registered package

Tooling
1

I have some packages which I do not intend to register in the Julia general registry. However, they the complete package structure, and I would like to use the TagBot, Docs, etc, as if the package was registered. Is that possible?

In particular, I do not know how to trigger TagBot and Documenter without calling the Julia registrator bot.

(ps: this package in particular, which I will call JuliaCookBook, will be a begginer-friendly -from my point of view, of course - collection of Julia examples, explanations, etc, which I will provide to students. I just do not think I have the proper knowledge to write “the” JuliaCookBook, so I do not want register that name for now).

2

You can just use git tag. Documenter should be triggered by that.

2 Likes
3

Oh, great. I thought it was something bound to the Julia registrator, not just to the tag.

4

Unfortunately it seems I was not lucky :frowning:

The TagBot does not appear to be launched automatically, and even if I run it manually it does not seem that anything happened. Any idea? The project is this one?

https://github.com/m3g/JuliaCookBook.jl

5

If I understand this correctly, you can do CI and docs without registering the package. TagBot is triggered by the Julia registry (or a private registry, maybe), so you might have do to the tagging yourself. I did not know about git tag and would be interested if you figure out how to get it to work.

Documenter, by default, makes your most recently tagged branch the “stable” branch and your master branch the “dev” branch. So if you roll your own tagging, you’ll get what you expect.

6

Actually I do not know what is the configuration file that I should add to trigger the generation of the Documentation. The TagBot is specifically saying that I sould remove it if the package is not going to be registered, and it does nothing because the package is not registered.

Tagging manually is easy, but I do not see how to trigger Documenter any other way. There is a “mkdocs.yml” file suggested in the Documenter docs, but adding it to the github actions returns errors.

7

I get documenter to run when I push new stuff (aside from md files). My docs.yml looks like this.
The line I commented out responds to skip-ci. When I learned how skip CI and docs after a README.md edit, I didn’t need it any more.

This works best if you also use github actions do to CI.

Studying PkgTemplates.jl really helped me.

name: Documentation

on:
  push:
    branches:
      - 'master'
      - 'release-'
    paths-ignore:
      - 'LICENSE.md'
      - 'README.md'
    tags: '*'
  pull_request:

jobs:
  build:
    runs-on: ${{ matrix.os }}
#    if: "!contains(github.event.head_commit.message, 'skip ci')"
    strategy:
      matrix:
        julia-version: [1.5]
        julia-arch: [x86]
        os: [ubuntu-latest]
    steps:
      - uses: actions/checkout@v2
      - uses: julia-actions/setup-julia@latest
        with:
          version: ${{ matrix.julia-version }}
      - name: Install dependencies
        run: julia --project=docs/ -e 'using Pkg;
              Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
      - name: Build and deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
        run: julia --project=docs --color=yes docs/make.jl
3 Likes
8

Ignore tagbot, you should not use it unless you register the package. Just git tag and push the tag should be enough, but you don’t have a workflow for actually building the documentation, so obviously nothing will happen when you push the tag.

4 Likes
9

Nice, that was not clear to me because when using PkgTemplate directly that specific file does not need to be present. Now the action is run. I didn’t get the docs yet, but I have something to search at least :slight_smile:

10

Now I got it… the file that was doing all the job in my other package was the ci.yml. I was confused by the fact that the documentation was generated associated with tags.

The only thing that is not working as I was expecting is that the gh-pages branch was not generated automatically, so that I do not get the pages yet. I will try to generate it by hand and see if that works.

11

After fixing some typos and releasing a new tag, it worked! :slight_smile:

Thank you all. I am not sure if you were asking me about the tags, @ctkelley, what I did after updating the yml file was to create a new release in the github page by clicking on Releases on the right hand, then Draft a new Release, and I created a new release with the name v0.1.0 and a tag of the type v0.1.0+doc1. That triggered the documentation and a stable version of the docs was built.

From the command line, the tags are added with, for example:

git tag -a v0.1.0+doc1 -m "v0.1.0"
git push --tag

https://m3g.github.io/JuliaCookBook.jl/stable/

3 Likes