Documentation

[bquorning]

I noticed that @bbatsov added three commits, adding some AsciiDoc documentation:

• 0d5031744078ab0787e0f92ff18828743daf6b69
• b15eefbf3d2e7261c38d30637e0eec36620bb055
• 97e8ebbac60845f83eab72d2cf2851a5c629fbb7

I cannot find any related PRs, so probably they were pushed directly to master (please don’t do that again 😄).

It seems we now have almost identical documents in manual/ and docs/ folders, but only the former is getting updated. What’s the plan? Should we change our documentation Rake task to update docs/ and delete the manual/ folder?

[bquorning]

I am asking party because I want to turn cops_documentation.rake into a class instead having all the code inside a Rake task, and that almost identical code exists in rubocop, rubocop-rails, and rubocop-performance, and I imagine rubocop-rake has, or would benefit from having, similar code.

[pirj]

That would be great to unify doc tasks with other repos. Since it's docs/ that get deployed to https://docs.rubocop.org/rubocop-rspec/, I guess we can retire manual/.

We still have a link in gemspec that points to https://rubocop.readthedocs.io/projects/rspec/en/latest/ though. Frankly, I have little to no idea how this documentation gets its way there. Somehow via a hook that uses mkdocs.yml?

https://www.rubydoc.info/find/github?q=rubocop-rspec returns 404. I remember @lsegal and @ioquatix maintain some other doc site, but can't quickly find it. Anyway, it seems rather unrelated, as such sites parse the code using class docs.

[bquorning]

Frankly, I have little to no idea how this documentation gets its way there. Somehow via a hook that uses mkdocs.yml?

I think #558 holds the answers to that question.

[bbatsov]

I'm surprised nobody noticed this so long, as we moved all the documentation about core RuboCop plugins to AsciiDoc/Antora recently. I even opened https://github.com/rubocop-hq/rubocop-rspec/issues/922 about the final missing point and I then I ran out of time for this.

Since it's docs/ that get deployed to https://docs.rubocop.org/rubocop-rspec/, I guess we can retire manual/.

Yep. There's one more thing to do, though - setting redirects from RTD to the new URLs. That's done from the admin UI.

I am asking party because I want to turn cops_documentation.rake into a class instead having all the code inside a Rake task, and that almost identical code exists in rubocop, rubocop-rails, and rubocop-performance, and I imagine rubocop-rake has, or would benefit from having, similar code.

Yeah, it'd be nice to dedup this. There's a lot of repetition in the maintenance code.

I cannot find any related PRs, so probably they were pushed directly to master (please don’t do that again smile).

Sorry about that. I was under the impression everyone new about this, as I recall it was discussed somewhere else. I guess I was wrong. :smile: The migration was done automatically, so there wasn't much to review there.

[bquorning]

Yep. There's one more thing to do, though - setting redirects from RTD to the new URLs. That's done from the admin UI.

I’m pretty sure I don’t have admin access at RTD. Maybe @bbatsov or @Darhazer has?

Sorry about that. I was under the impression everyone new about this, as I recall it was discussed somewhere else. I guess I was wrong. 😄

I kinda knew that the md -> asciidoc conversion was happening, but I wasn’t sure about the state of things. And while I notice most PR’s, I didn’t notice you committing directly to the master branch :-)

And that said, I completely missed #922. Sorry about that.

Just a question: How do the files in docs/ get sync’ed to the documentation site?

[bbatsov]

Right now it's manual - https://docs.rubocop.org/rubocop/0.87/contributing.html#documentation

The new docs site pulls all documentation modules from all the repos and builds the combined site. The only thing to keep in mind is that antora.yml has to be updated when cutting releases and that new tags have to be added to the antora-playbook.yml in docs.rubocop.org repo. At some point I plan to automate this via GitHub actions, but I didn't have enough time to play with them.

[bquorning]

WIP at https://github.com/rubocop-hq/rubocop-rspec/compare/asciidoc-documentation – will create PR later.

[bbatsov]

Looks good!

[bquorning]

In the last RuboCop release, I see that antora.yml was changed right before the release, and again right after:

• https://github.com/rubocop-hq/rubocop/commit/829c782697438e381d702e4dc6c5b25cfbb69404
• https://github.com/rubocop-hq/rubocop/commit/7685308b7444ccf97e3413596d55a74957ed1656

I am not sure if the docs upload/pull process was manual or automated.

[koic]

Hi, @bquorning

am not sure if the docs upload/pull process was manual or automated.

It is automated by the following repository. https://github.com/rubocop-hq/docs.rubocop.org

For the release of rubocop-rspec 1.43.0:

1. Update docs/antora.yml in rubocop-rspec repository (from version: master to version: '1.43') [example]
2. Release rubocop-rspec 1.43.0 (and git tagging)
3. Switch back docs/antora.yml in rubocop-rspec repository (from version: '1.43' to version: master) [example]
4. % cd docs.rubocop.org
5. Add rubocop-rspec 1.43.0 version to antora-playbook.yml in docs.rubocop.org repository [example]
6. Run $ antora --pull antora-playbook.yml
7. Run $ ./deploy [script]

NOTE: no patch version is required for docs/antora.yml in rubocop-rspec repository. And specify the patch version in antora-playbook.yml in docs.rubocop.org repository.

If you have any questions, please ask me :-)

[bbatsov]

NOTE: no patch version is required for docs/antora.yml in rubocop-rspec repository.

Let me add a bit of detail here - I've opted not to include the patch version mostly to avoid publishing the same documentation twice (we should just use whatever the latest patch version is to publish the docs for a particular release).

[bquorning]

Is step 3 really necessary?

[koic]

Yep. I've once encountered this troubleshooting 😅 https://github.com/rubocop-hq/docs.rubocop.org#troubleshooting

[bbatsov]

You'd get an error from Antora saying that the same docs version exists in multiple branches if you don't do it. (as the version is the defined by antora.yml, not by the git branch version)

[pirj]

@bquorning Do you think there's anything actionable left here?

[bquorning]

I think we should add an “internal readme” with notes on the things to remember when deploying, including the notes from https://github.com/rubocop-hq/rubocop-rspec/issues/972#issuecomment-670306179