Integrate docs into the main repo

[nickva]

Related to the discussion in dev ML

The main advantage for doing it are:

• No need to create a separate PR for features. Less efforts to update docs.
• Make it easier to generate releases. Release notes track source changes.
• Speed up ./configure as there one less dependency to fetch.

One of the objections of this approach, as discussed in the ML, was that docs PRs have a lightweight CI and we'd want to preserve that. This PR attempts to address that with the changes to the Jenkinsfile.pr (thanks to @big-r81 for the idea in the ML) where the following logic is used in the when ... stage triggers.

• If any docs files are changed, run docs make check (a quick format check for docs)
• If only docs changed, then docs make is run, like in the previous separate docs repo. All the other CI steps are skipped.
• If other files are changed, not just docs, then the full CI is run. As part of that make dist also builds docs. If this happens there is not need to also run the "Build Docs" so that can be skipped.

[nickva]

To better illustrate how it works here are the cases described above generated with a few bogus PRs into this branch:

Docs only

Docs and source changes

Source only changes

[big-r81]

Great work Nick!

Some informational reminders:

1. Are all tags set in main like in docs-main
2. Change link in RTD
3. Document change in couchdb-documentation
4. Archive couchdb-documentation?
5. Any links to update?
6. Any open PR’s need to get merged first?
7. Something I forgot?

[nickva]

Good points, @big-r81

RTD allows configuring which branches/tags to build. I think we could keep stable (which is an alias to 3.2.2) and latest. latest is automatically built from main. stable can be either an explicit branch, or if that's missing it's automatically the highest semver release tag (the one we use). But our 3.2.2 tag in the main repo won't build the moved docs. So thinking of making a 3.2.2-docs branch with the integrated docs for 3.2.2 for that case.

As for archiving we could just update the main branch and put just a readme file indicating to move the pull request to the main repo.. After some time we can archive it too.

Unfortunately the pending PRs would have to be re-targeted for the main repo.

I think there would be some links / example readme changes.

[jaydoane]

Have a few comments, but it appears I was too late!

[big-r81]

Maybe it’s a good idea to define an .editorconfig for the project / projects?

[nickva]

Have a few comments, but it appears I was too late!

It’s never too late! Will fix it in a separate PR. Thanks for taking a look, @jaydoane

[nickva]

I tried this in .emacs:

'(groovy-indent-offset 2)

I'll reformat both the full and pr files

[nickva]

@jaydoane #4171

[nickva]

Maybe it’s a good idea to define an .editorconfig for the project / projects?

I wonder if emacs could read that? For erlang it's relatively straightforward as we're using erlfmt but for other languages it's a bit unspecified.

[big-r81]

Maybe it’s a good idea to define an .editorconfig for the project / projects?

I wonder if emacs could read that? For erlang it's relatively straightforward as we're using erlfmt but for other languages it's a bit unspecified.

https://github.com/editorconfig/editorconfig-emacs