Convert technical docs to Antora by andreslucena · Pull Request #6526 · decidim/decidim

andreslucena · 2020-09-16T15:10:20Z

🎩 What? Why?

In the last months, I've been making some changes in the Documentation site, with the idea of having only a repository. After some discussion at #6382 I wanted to try how it'd look like to have some of the technical docs available in this repository. This is it.

It also brings some more changes to the current docs that I noticed were missing or could be improved:

Update install instructions, also changes scheduled tasks for easier copy pasting: https://docs.decidim.org/en/install/
Add update instructions based in Platoniq's guide
Add some configuration doc
Better explanation about JS
Menu customization (proposed by @AbcSxyZ see Documentation : Customize homepage navbar #6353)
Better explanation about CSS
A short explanation about SMTP
Remove Analytics service (it should be done compatible with OSP's cookies module)
Some rework on Development Guide
Moved Docker development instructions to its own section

There are a couple of new changes that are only in the PR preview for the branch at the documentation repository (not yet in production):

Order some sections inside "Advanced": Views and Concerns. As there are too many docs in this section, it's important to give some ordering:

Rename some concerns so they're consistent ("-able" suffix)
Configuring ENV_VARS and initializer docs
C4 model graphics for our architecture. That means that with some plain text code we get drawings:

(Input) C4 PlantUML snippet

[plantuml]
....
@startuml
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Context.puml
LAYOUT_TOP_DOWN
' uncommetn the following line to make proposals
'LAYOUT_AS_SKETCH
title System Context diagram for Decidim Applications (https://decidim.org)
Person_Ext(visitor_user, "Visitor User", "Anonymous, non registered user.")
Person(participant_user, "Participant User", "A registered user. Could also be verified.")
Person(administration_user, "Administration User", "A registered user with special permissions.")
System(decidim_system, "Decidim", "Allows participants to make decisions collaboratively through participatory processes, assemblies, consultations, initiatives, etc.")
System_Ext(mail_system, "SMTP system (e-mail)", "Sends mails to users, like confirmations, reminders, notifications, etc.")
System_Ext(etherpad_system, "Etherpad-Lite system", "Optional. Allows real-time text edition in Meetings.")
System_Ext(geocoding_system, "Geocoding system", "Optional. An Open Street Maps provider, allows geographical localization of Proposals and Meetings..")
System_Ext(oauth_system, "OAUTH2 System", "Optional. Third party sign on systems. Could be Twitter, Facebook, Google or any other OAUTH2 providers.")
Rel(visitor_user, decidim_system, "Uses")
Rel(participant_user, decidim_system, "Uses")
Rel(administration_user, decidim_system, "Uses")
Rel_Back(participant_user, mail_system, "Sends e-mails to")
Rel_Back(administration_user, mail_system, "Sends e-mails to")
Rel_Neighbor(decidim_system, mail_system, "Sends e-mails", "SMTP")
Rel(decidim_system, oauth_system, "Uses")
Rel(decidim_system, geocoding_system, "Uses")
Rel(decidim_system, etherpad_system, "Embeds", "Through an Iframe")
@enduml
....

(Output) C4 PlantUML graph

There are some things that I'm not happy yet [*] but I want to get some more eyes before I continue with this.

[*] Things for improvement/discussion:

I think the services module should be inside of configure. configure/customize/services tree is just weird.
There are some things that are duplicated, for instance Contribute with CONTRIBUTING.md and Security with SECURITY.md. I think the Markdown files should be the single source of true as they're more standard and better integrated with Github and we should add an alert from docs site linking back to this repository.

📌 Related Issues

📋 Subtasks

Add documentation regarding the feature

andreslucena · 2020-10-01T09:31:17Z

A couple of comments:

I don't find any linter for AsciiDoc so we can integrate with GitHub Actions :(
For consistency and not context switching between syntaxes, I think we should probably also convert the README.md to README.adoc. GitHub also parses it so it's not an issue for the end-user (see Example).

Leusev

Great and huge work here @andreslucena 👏
I either didn't found Elections Bulletin Board .md file into this PR possibly due to being recently merged.

Really interesting to take a look at this PR @tramuntanal @ivan-mr @microstudi

docs/modules/develop/pages/guide.adoc

docs/modules/develop/pages/docker.adoc

docs/modules/develop/pages/components.adoc

docs/modules/develop/pages/machine_translations.adoc

docs/modules/develop/pages/managing_translations_i18n.adoc

docs/modules/develop/pages/permissions.adoc

docs/modules/develop/pages/view_models_aka_cells.adoc

Leusev · 2020-10-06T13:20:20Z

docs/modules/services/pages/geocoding.adoc

@@ -1,34 +1,35 @@
-# Geocoding
+= Geocoding


Maybe this section it could be reworked as due to PR #6340 made changes and restructured this section, making disappear geocoding.md in favor of maps.md

Same as my other comment, I need to manually merge last commits

Fixed that: #6526 (comment)

Leusev · 2020-10-06T13:29:28Z

Btw, the [CI] Meetings test has already been solved with PR #6595 , so with a develop's merge will be fixed here too.

andreslucena · 2020-10-06T16:19:38Z

Btw, the [CI] Meetings test has already been solved with PR #6595 , so with a develop's merge will be fixed here too.

I merged with develop.

I've also manually converted the new documents. Mind that for appearing in the new site is necessary to also add the new file references at the other repository:

https://deploy-preview-30--decidim-documentation.netlify.app/en/services/elections_bulletin_board/
https://deploy-preview-30--decidim-documentation.netlify.app/en/services/maps/
https://deploy-preview-30--decidim-documentation.netlify.app/en/develop/fixing_locales/
https://deploy-preview-30--decidim-documentation.netlify.app/en/develop/maps/
https://deploy-preview-30--decidim-documentation.netlify.app/en/develop/templates/

Leusev · 2020-10-07T06:30:30Z

docs/modules/customize/pages/oauth.adoc

+Decidim is both and OAuth client (via https://github.com/omniauth/omniauth[omniauth]) and an OAuth provider (via https://github.com/doorkeeper-gem/doorkeeper[doorkeeper]).

-Check the [Social Providers](https://github.com/decidim/decidim/blob/master/docs/services/social_providers.md) document to check the client configuration.
+Check the https://github.com/decidim/decidim/blob/master/docs/services/social_providers.md[Social Providers] document to check the client configuration.


If PR #6607 is merged, then this section would have to be updated too..

Ok, I've already migrated that (I think 😅)

tramuntanal · 2020-10-07T06:54:38Z

Interesting PR @andreslucena !

Let's wait to branch off release/0.23-stable before merging this @Leusev

tramuntanal · 2020-10-09T11:37:29Z

I've synced #6607

qlty-cloud-legacy

The PR diff size of 6900 lines exceeds the maximum allowed for the inline comments feature.

andreslucena · 2020-11-17T08:37:58Z

Let's wait to branch off release/0.23-stable before merging this @Leusev

0.23 was released already, can we please review and merge this PR @tramuntanal @Leusev?

It's especially difficult to keep track of this because docs/ files change, sometimes there are cosmetic changes, and also there's another repository and publish process involved in this change (https://github.com/decidim/documentation and https://docs.decidim.org).

Thanks!!

qlty-cloud-legacy

The PR diff size of 6900 lines exceeds the maximum allowed for the inline comments feature.

tramuntanal · 2020-11-19T07:49:57Z

ok @andreslucena , can you rebase with develop please so we get rid of many diffs in the "Files changed" tab, and also have the docs/services/elections_bulletin_board.md conflicts solved?

@Leusev let's prioritize this PR as we don't want to loos changes in the docs.

qlty-cloud-legacy

The PR diff size of 6902 lines exceeds the maximum allowed for the inline comments feature.

I've reviewed all the review and I think I've tackled all the comments

Adds sections: * configure * customize * develop * install * services Also adds: * a README explaining the relationship with the documentation repository available in https://github.com/decidim/documentation * antora metadata file so we can build these sections in the same website

…ramuntanal

…ramuntanal Extracted from #6607

Extracted from #6794

Extracted from #6677

qlty-cloud-legacy

The PR diff size of 6087 lines exceeds the maximum allowed for the inline comments feature.

andreslucena · 2020-11-19T12:44:59Z

ok @andreslucena , can you rebase with develop please so we get rid of many diffs in the "Files changed" tab, and also have the docs/services/elections_bulletin_board.md conflicts solved?

I've rebased it already. The conflicts in docs/services/elections_bulletin_board.md are solved.

Leusev

Hi @andreslucena
in first place, congratulations on your recent good personal news 😉 😄
By other side, sorry for the delay in tackling this PR, I reviewed again, looks good now, only needs to solve new docs/advanced/releases.md conflict file
Thank you so much for this great documentation restructuring effort

qlty-cloud-legacy

The PR diff size of 6087 lines exceeds the maximum allowed for the inline comments feature.

qlty-cloud-legacy

The PR diff size of 6102 lines exceeds the maximum allowed for the inline comments feature.

andreslucena · 2020-12-02T08:44:57Z

in first place, congratulations on your recent good personal news wink smile

Thanks! ❤️

By other side, sorry for the delay in tackling this PR, I reviewed again, looks good now, only needs to solve new docs/advanced/releases.md conflict file

OK, I merged again and resolved the conflict, it's OK now

Thank you so much for this great documentation restructuring effort

Awesome, I hope that everyone enjoy Antora/AsciiDoc also, it has a learning cure but is really well suited for documentation sites. 😄

Leusev

Looks good for me @andreslucena 👍
As I said before, thanks a lot for that huge effort & work. I'll merge it! 🎉

…ngs_content_block * develop: (22 commits) Fix email CTA alignment on Outlook and Windows Mail (#6895) Fix mailer meeting registration invitation using path instead of URL (#6965) Fix the data portability exporter when zip is not in the gemfile (#6969) Convert technical docs to Antora (#6526) New Crowdin updates (#6957) Bugfix - moderated meetings are displayed in the meetings index page (#6927) Add HTML Content Blocks in Process Groups (#6823) Prevent error in view due to optional html not showing (#6942) Improve layout for standalone T&C page (#6944) chore: move rubocop ruby config to own file (#6952) Fix some strings (#6958) Fix newsletter html containing style tag content (#6876) New Crowdin updates (#6945) New Crowdin updates (#6926) Localize a string in conference speaker (#6866) Fix broken dashboard action logs under certain conditions (#6857) Fix traceability logs with invalid record (#6879) Allow user to drag address on proposal map (#6291) New Crowdin updates (#6898) Update release notes documentation (#6809) ...

…_content_block * develop: (22 commits) Fix email CTA alignment on Outlook and Windows Mail (#6895) Fix mailer meeting registration invitation using path instead of URL (#6965) Fix the data portability exporter when zip is not in the gemfile (#6969) Convert technical docs to Antora (#6526) New Crowdin updates (#6957) Bugfix - moderated meetings are displayed in the meetings index page (#6927) Add HTML Content Blocks in Process Groups (#6823) Prevent error in view due to optional html not showing (#6942) Improve layout for standalone T&C page (#6944) chore: move rubocop ruby config to own file (#6952) Fix some strings (#6958) Fix newsletter html containing style tag content (#6876) New Crowdin updates (#6945) New Crowdin updates (#6926) Localize a string in conference speaker (#6866) Fix broken dashboard action logs under certain conditions (#6857) Fix traceability logs with invalid record (#6879) Allow user to drag address on proposal map (#6291) New Crowdin updates (#6898) Update release notes documentation (#6809) ...

…cipatory_processes_content_block * develop: (22 commits) Fix email CTA alignment on Outlook and Windows Mail (#6895) Fix mailer meeting registration invitation using path instead of URL (#6965) Fix the data portability exporter when zip is not in the gemfile (#6969) Convert technical docs to Antora (#6526) New Crowdin updates (#6957) Bugfix - moderated meetings are displayed in the meetings index page (#6927) Add HTML Content Blocks in Process Groups (#6823) Prevent error in view due to optional html not showing (#6942) Improve layout for standalone T&C page (#6944) chore: move rubocop ruby config to own file (#6952) Fix some strings (#6958) Fix newsletter html containing style tag content (#6876) New Crowdin updates (#6945) New Crowdin updates (#6926) Localize a string in conference speaker (#6866) Fix broken dashboard action logs under certain conditions (#6857) Fix traceability logs with invalid record (#6879) Allow user to drag address on proposal map (#6291) New Crowdin updates (#6898) Update release notes documentation (#6809) ...

…link * develop: (22 commits) Fix email CTA alignment on Outlook and Windows Mail (#6895) Fix mailer meeting registration invitation using path instead of URL (#6965) Fix the data portability exporter when zip is not in the gemfile (#6969) Convert technical docs to Antora (#6526) New Crowdin updates (#6957) Bugfix - moderated meetings are displayed in the meetings index page (#6927) Add HTML Content Blocks in Process Groups (#6823) Prevent error in view due to optional html not showing (#6942) Improve layout for standalone T&C page (#6944) chore: move rubocop ruby config to own file (#6952) Fix some strings (#6958) Fix newsletter html containing style tag content (#6876) New Crowdin updates (#6945) New Crowdin updates (#6926) Localize a string in conference speaker (#6866) Fix broken dashboard action logs under certain conditions (#6857) Fix traceability logs with invalid record (#6879) Allow user to drag address on proposal map (#6291) New Crowdin updates (#6898) Update release notes documentation (#6809) ...

…ighted_groups * develop: (22 commits) Fix email CTA alignment on Outlook and Windows Mail (#6895) Fix mailer meeting registration invitation using path instead of URL (#6965) Fix the data portability exporter when zip is not in the gemfile (#6969) Convert technical docs to Antora (#6526) New Crowdin updates (#6957) Bugfix - moderated meetings are displayed in the meetings index page (#6927) Add HTML Content Blocks in Process Groups (#6823) Prevent error in view due to optional html not showing (#6942) Improve layout for standalone T&C page (#6944) chore: move rubocop ruby config to own file (#6952) Fix some strings (#6958) Fix newsletter html containing style tag content (#6876) New Crowdin updates (#6945) New Crowdin updates (#6926) Localize a string in conference speaker (#6866) Fix broken dashboard action logs under certain conditions (#6857) Fix traceability logs with invalid record (#6879) Allow user to drag address on proposal map (#6291) New Crowdin updates (#6898) Update release notes documentation (#6809) ...

…s_and_processes_block * develop: (22 commits) Fix email CTA alignment on Outlook and Windows Mail (#6895) Fix mailer meeting registration invitation using path instead of URL (#6965) Fix the data portability exporter when zip is not in the gemfile (#6969) Convert technical docs to Antora (#6526) New Crowdin updates (#6957) Bugfix - moderated meetings are displayed in the meetings index page (#6927) Add HTML Content Blocks in Process Groups (#6823) Prevent error in view due to optional html not showing (#6942) Improve layout for standalone T&C page (#6944) chore: move rubocop ruby config to own file (#6952) Fix some strings (#6958) Fix newsletter html containing style tag content (#6876) New Crowdin updates (#6945) New Crowdin updates (#6926) Localize a string in conference speaker (#6866) Fix broken dashboard action logs under certain conditions (#6857) Fix traceability logs with invalid record (#6879) Allow user to drag address on proposal map (#6291) New Crowdin updates (#6898) Update release notes documentation (#6809) ...

This was referenced Sep 28, 2020

Add vagrant configuration #6454

Closed

Change default initializer settings #6566

Merged

Leusev self-requested a review October 6, 2020 09:57

Leusev added in-review team: documentation labels Oct 6, 2020

Leusev previously requested changes Oct 6, 2020

View reviewed changes

Leusev reviewed Oct 7, 2020

View reviewed changes

tramuntanal mentioned this pull request Oct 7, 2020

Update documentation for decidim OAuth social provider #6607

Merged

12 tasks

andreslucena mentioned this pull request Oct 8, 2020

Adding a translator on Crowdin to the French language #6603

Closed

qlty-cloud-legacy bot reviewed Nov 17, 2020

View reviewed changes

andreslucena requested a review from Leusev November 17, 2020 08:42

qlty-cloud-legacy bot reviewed Nov 17, 2020

View reviewed changes

qlty-cloud-legacy bot reviewed Nov 19, 2020

View reviewed changes

andreslucena added 9 commits November 19, 2020 12:31

Remove Markdown doc

32438b0

Fix Antora name for docs

016ed39

Rename advanced pages to Concerns

582fe1a

Add Authorizations customize from module's README

c50c3e9

Move 'add_authorizable_action' to 'permissions'

90ba25c

Move 'adding_fixtures_aka_dummy_content' to 'components'

01cb0fa

Move 'how_to_create_a_module' to 'components'

7588674

Remove 'upgrading', now it's in 'update'

1b689c1

andreslucena and others added 9 commits November 19, 2020 12:35

Convert CONTRIBUTING.md to AsciiDoc

c3e2b37

Convert README.md to AsciiDoc

cb11824

Clarify CONTRIBUTING and links to docs site

70140ff

Remove Markdown linter CI

aa8a802

Sync "Update documentation for decidim OAuth social provider" by @t…

43105e4

…ramuntanal Extracted from #6607

Sync "Generate changelog entries" by @tramuntanal

dd3a54c

Extracted from #6794

Fix link in oauth.adoc

a719b3f

Sync "Improve moderation panel" by @beagleknight

c4f6b4c

Extracted from #6677

Removes trailing whitespaces

b1ed206

andreslucena force-pushed the doc/antora-docs branch from af541be to b1ed206 Compare November 19, 2020 11:36

qlty-cloud-legacy bot reviewed Nov 19, 2020

View reviewed changes

Leusev suggested changes Nov 25, 2020

View reviewed changes

qlty-cloud-legacy bot reviewed Nov 25, 2020

View reviewed changes

andreslucena added 2 commits November 30, 2020 10:52

Merge branch 'develop' into doc/antora-docs

4d11b96

Merge branch develop

38a5852

qlty-cloud-legacy bot reviewed Nov 30, 2020

View reviewed changes

Leusev self-requested a review December 2, 2020 15:20

Leusev approved these changes Dec 2, 2020

View reviewed changes

Leusev merged commit 037b393 into develop Dec 2, 2020

Leusev deleted the doc/antora-docs branch December 2, 2020 15:23

andreslucena mentioned this pull request Dec 3, 2020

Fix README adoc #6979

Merged

12 tasks

mrcasals added the target: developer-experience label Feb 26, 2021

Uh oh!

Conversation

andreslucena commented Sep 16, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎩 What? Why?

📌 Related Issues

📋 Subtasks

Uh oh!

andreslucena commented Oct 1, 2020

Uh oh!

Leusev left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Leusev Oct 6, 2020

Choose a reason for hiding this comment

Uh oh!

andreslucena Oct 6, 2020

Choose a reason for hiding this comment

Uh oh!

andreslucena Oct 6, 2020

Choose a reason for hiding this comment

Uh oh!

Leusev commented Oct 6, 2020

Uh oh!

andreslucena commented Oct 6, 2020

Uh oh!

Leusev Oct 7, 2020

Choose a reason for hiding this comment

Uh oh!

andreslucena Nov 19, 2020

Choose a reason for hiding this comment

Uh oh!

tramuntanal commented Oct 7, 2020

Uh oh!

tramuntanal commented Oct 9, 2020

Uh oh!

qlty-cloud-legacy bot left a comment

Choose a reason for hiding this comment

Uh oh!

andreslucena commented Nov 17, 2020

Uh oh!

qlty-cloud-legacy bot left a comment

Choose a reason for hiding this comment

Uh oh!

tramuntanal commented Nov 19, 2020

Uh oh!

qlty-cloud-legacy bot left a comment

Choose a reason for hiding this comment

Uh oh!

qlty-cloud-legacy bot left a comment

Choose a reason for hiding this comment

Uh oh!

andreslucena commented Nov 19, 2020

Uh oh!

Leusev left a comment

Choose a reason for hiding this comment

Uh oh!

qlty-cloud-legacy bot left a comment

Choose a reason for hiding this comment

Uh oh!

qlty-cloud-legacy bot left a comment

Choose a reason for hiding this comment

Uh oh!

andreslucena commented Dec 2, 2020

Uh oh!

Leusev left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

andreslucena commented Sep 16, 2020 •

edited

Loading

Leusev left a comment •

edited

Loading