Skip to content

Make documentation site work with multiple versions#9917

Merged
ahukkanen merged 5 commits intodevelopfrom
feature/multiversion-documentation
Oct 26, 2022
Merged

Make documentation site work with multiple versions#9917
ahukkanen merged 5 commits intodevelopfrom
feature/multiversion-documentation

Conversation

@andreslucena
Copy link
Copy Markdown
Member

@andreslucena andreslucena commented Oct 20, 2022

🎩 What? Why?

As I mentioned in #9916, we have a problem that currently instructions in https://docs.decidim.org are always on develop. This is problematic, some examples from http://chat.decidim.org from the last couple of months:

  • Users were trying to use Environment Variables that weren't there for v0.26
  • Users were trying to install v0.27 with Ruby v.2.7.5 (it should be v3.0.2)

📌 Related Issues

Testing

As there are two repositories each with 3 branches it's tricky to try this out locally. What I've done is:

git fetch origin
git checkout release/0.26-stable 
# Change docs/antora.yml version to v0.26
git add docs/antora.yml  && git commit -m "Bump version for Antora"
git checkout release/0.27-stable 
# Change docs/antora.yml version to v0.27
git add docs/antora.yml  && git commit -m "Bump version for Antora"
git checkout develop 
# Change docs/antora.yml version to develop
git add docs/antora.yml  && git commit -m "Bump version for Antora"

# In another directory
git clone https://github.com/decidim/documentation.git
cd documentation 
npm install 
git fetch origin 
git checkout develop 
# Change the url in the decidim/decidim source to your local path, ie /home/apereira/Work/decidim/decidim 
npm run build
xdg-open build/site/index.html

Mind that if you don't do all these steps, you'll have this error message:

$ npm run build

> decidim-documentation@ build /home/apereira/Work/decidim/documentation
> antora antora-playbook.yml $@

[17:07:21.941] FATAL (antora): Duplicate page: master@en:configure:environment_variables.adoc
  1: docs/modules/configure/pages/environment_variables.adoc in https://github.com/decidim/decidim (ref: develop)
  2: docs/modules/configure/pages/environment_variables.adoc in https://github.com/decidim/decidim (ref: release/0.26-stable)
Add the --stacktrace option to see the cause of the error.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! decidim-documentation@ build: `antora antora-playbook.yml $@`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the decidim-documentation@ build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/apereira/.npm/_logs/2022-10-20T15_07_21_995Z-debug.log

This is because you don't have the correct version names or URLs configured in your repositories.

📷 Screenshots

(The idea is that after #9916 is merged, when you go to develop you'll have ruby 3.1.1, but on v0.27 you'll have 3.0.2)

doc-muilti-version-branches.mp4

♥️ Thank you!

This was referenced Oct 20, 2022
Merged
Merged
@andreslucena
Copy link
Copy Markdown
Member Author

andreslucena commented Oct 20, 2022

Mind that for this to work on https://docs.decidim.org, we'll also need to change the Antora default branch. We can do that after these three PRs are merged (#9917, #9918 and #9919)

ahukkanen
ahukkanen requested changes Oct 25, 2022
View reviewed changes
Copy link
Copy Markdown
Contributor

@ahukkanen ahukkanen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really nice improvement! Something that will be extremely useful for everyone.

Just one suggestion below as I think the more we can automate things, the less mistakes we will make along the line.

ahukkanen
ahukkanen requested changes Oct 25, 2022
View reviewed changes
Copy link
Copy Markdown
Contributor

@ahukkanen ahukkanen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One more small cleanup.

@andreslucena andreslucena added team: documentation type: internal PRs that aren't necessary to add to the CHANGELOG for implementers labels Oct 26, 2022
@ahukkanen ahukkanen merged commit 7db8925 into develop Oct 26, 2022
@ahukkanen ahukkanen deleted the feature/multiversion-documentation branch October 26, 2022 08:29
entantoencuanto added a commit that referenced this pull request Oct 26, 2022
@entantoencuanto
Merge branch 'develop' into feature/redesign-verifications
7acb16e 
* develop: (35 commits)
  Install turbo-rails (#9881)
  Fix conference invitations (#9664)
  Fix invalid rendering of meeting and proposal body texts (#9764)
  Make documentation site work with multiple versions (#9917)
  Bump versions on install docs (#9916)
  Standardize CSV import formats and fix private users CSV import with invalid file (#9627)
  Fix: The i18n locales selector is showing a dropdown with 3 languages (#9902)
  Make Scopes field in debates translatable (#9903)
  Make ToS agreement translatable (#9909)
  Fix issues with a11y specs (#9929)
  Remove invitations badge (#9906)
  Make initiatives order translatable (#9905)
  Add missing active actions on admin navigation menu (#9904)
  Fix user sign up with invalid name (#9896)
  Remove duplication of LastActivity queries (#9895)
  Rename IgnoredMethods to AllowedMethods in Rubocop configuration (#9893)
  Exclude malformed file from codeclimate configuration (#9910)
  Fix correct resource linking for amendments (#9887)
  Fix superposition in admin's error forms (#9871)
  Add missing i18n key in Initiatives (#9892)
  ...
entantoencuanto added a commit that referenced this pull request Oct 31, 2022
@entantoencuanto
Merge branch 'develop' into borrame18
428a2de 
* develop: (36 commits)
  Fix proposal etiquette and length validator with base64 images (#9639)
  Install turbo-rails (#9881)
  Fix conference invitations (#9664)
  Fix invalid rendering of meeting and proposal body texts (#9764)
  Make documentation site work with multiple versions (#9917)
  Bump versions on install docs (#9916)
  Standardize CSV import formats and fix private users CSV import with invalid file (#9627)
  Fix: The i18n locales selector is showing a dropdown with 3 languages (#9902)
  Make Scopes field in debates translatable (#9903)
  Make ToS agreement translatable (#9909)
  Fix issues with a11y specs (#9929)
  Remove invitations badge (#9906)
  Make initiatives order translatable (#9905)
  Add missing active actions on admin navigation menu (#9904)
  Fix user sign up with invalid name (#9896)
  Remove duplication of LastActivity queries (#9895)
  Rename IgnoredMethods to AllowedMethods in Rubocop configuration (#9893)
  Exclude malformed file from codeclimate configuration (#9910)
  Fix correct resource linking for amendments (#9887)
  Fix superposition in admin's error forms (#9871)
  ...
Quentinchampenois pushed a commit to Quentinchampenois/decidim that referenced this pull request Nov 23, 2022
@andreslucena @Quentinchampenois
Make documentation site work with multiple versions (decidim#9917)
7eee58e 
* Change version name in Antora configuration

* Add docs for changing versions on documentation site

* Automate changing versions with GemManager.replace_versions

* Remove unnecessary assigment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ahukkanen ahukkanen ahukkanen approved these changes

Assignees

No one assigned

Labels

team: documentation type: internal PRs that aren't necessary to add to the CHANGELOG for implementers

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@andreslucena @ahukkanen