Restructure the documentation #3259

gustawlippa · 2021-09-10T09:07:13Z

This PR updates the documentation so that it is more readable.

Changes:

The structure is updated as described in the proposal on Confluence,
Typos fixed, language improved, issues fixed in multiple files,
Added admonitions, which are these pretty things:
Added an installation guide,
Added content tabs, which allow to choose different versions/options of described content:
Renamed the folders to better reflect the content (but I don't know if exactly following the section names is needed, so for now e.g. "Extension modules" section is still inside "modules")
Added a logo:

If you want to see the changes from this PR locally, follow https://squidfunk.github.io/mkdocs-material/getting-started/

NelsonVides

The main page stopped working, if you just enter the site it says 404.

NelsonVides · 2021-09-16T09:18:13Z

The main page stopped working, if you just enter the site it says 404.

https://nelsonvides.github.io/MongooseIM/latest/ 😕

gustawlippa · 2021-09-16T09:18:23Z

Yeah, I've just noticed it as well. It seems that the "Home" page is needed in the end for links to work correctly etc. :/
Your link would work as https://nelsonvides.github.io/MongooseIM/latest/getting-started/Overview/ , but yeah, we don't want that probably. I will fix it, but this will change the whole structure... aaargh.

NelsonVides · 2021-09-16T12:09:02Z

mkdocs.yml

-      - 'Getting started': 'user-guide/Getting-started.md'
-      - 'Release/Installation configuration': 'user-guide/release_config.md'
-      - 'Bootstrap scripts': 'user-guide/Bootstrap-Scripts.md'
-      - 'Client certificate authentication': 'user-guide/client-certificate.md'
  - Tutorials:
      - 'How to Build MongooseIM from source code': 'user-guide/How-to-build.md'


I'd reorganise the file locations as well, now we'd have for example the How-to-build page in the Tutorials section but in the user-guide directory, which is confusing, also because their filepath is what is later shown in the URL. I think the sections in the site and the directories should match.

I agree, I was thinking there might have been a reason to have tutorials in the user-guide directory, so I left it as it was. But I'm glad you see it this way, will be reorganised.

I've also renamed "advanced-configuration" to just "configuration"

chrzaszcz

Thanks for this huge bunch of improvements! I only found a few places where it could be improved.

chrzaszcz · 2021-09-17T11:29:44Z

README.md

+    * [Set up MongooseICE](https://esl.github.io/MongooseDocs/latest/user-guide/ICE_tutorial.md)
+    * [Build an iOS messaging app](https://esl.github.io/MongooseDocs/latest/user-guide/iOS_tutorial.md)
+* [User Guide](https://esl.github.io/MongooseDocs/latest/user-guide/Features/). Learn all about how to use MongooseIM in your project. Explore its features, supported XEPs, RFCs and database backends, as well as its architecture and deployment strategies.
+* [Configuration](https://esl.github.io/MongooseDocs/latest/advanced-configuration/configuration-files/). Explore available options including database backend configuration, access control lists, listener and extension modules.


Shouldn't we drop advanced? And btw, why are these links absolute?

Yes, advanced should be dropped - good catch! There are also some other broken links.
I've changed some of the links to be absolute, because:

The section is "documentation highlights", so for me it seems it should lead to our hosted documentation.

Some of the links were already absolute, so it was really unifying them one way or the other.

doc/getting-started/Quick-setup.md

chrzaszcz · 2021-09-17T12:48:46Z

doc/migrations/4.2.0_5.0.0.md

@@ -3,21 +3,22 @@
 The migrations scripts for Postgres, MySQL, MSSQL can be found in the [`priv/migrations`](../../priv/migrations/) directory. Please remember to provide the existing server domain for the `server` column instead of the localhost.

 ### Changes in XEPs:
- `mod_last` 
-   - Table `last` - added server column, updated primary key and indexes.
+


Note: the link to priv/migrations above does not work as it references a file in the repo outside of the docs directory. Maybe replace with a GitHub link?

I think so. This is the similar case to linking the documentation from README.md. These links will work in GitHub, but a full link should not cause any problems.

chrzaszcz

It looks good, I just think it would be nice to let CI run the "build docs" job by removing skip ci for the last commit before merging.

The introduction to MIM used to be a bit chaotic, and the "User Guide" section was too big. Now, with the new "Getting started" section, the first impressions should be much better.

See squidfunk.github.io/mkdocs-material/reference/admonitions for more information.

Turns out a page at the top level of the documentation is needed for links to work correctly. That's why we are going back to the index.md "Home" page.

Apply suggestions from code review Co-authored-by: Paweł Chrząszcz <[email protected]>

mongoose-im · 2021-09-17T14:36:18Z

small_tests_24 / small_tests / c90c618
Reports root / small

internal_mnesia_24 / internal_mnesia / c90c618
Reports root/ big
OK: 1589 / Failed: 0 / User-skipped: 290 / Auto-skipped: 0

small_tests_22 / small_tests / c90c618
Reports root / small

small_tests_23 / small_tests / c90c618
Reports root / small

dynamic_domains_24 / pgsql_mnesia / c90c618
Reports root/ big
OK: 2654 / Failed: 0 / User-skipped: 183 / Auto-skipped: 0

dynamic_domains_23 / pgsql_mnesia / c90c618
Reports root/ big
OK: 2654 / Failed: 0 / User-skipped: 183 / Auto-skipped: 0

ldap_mnesia_24 / ldap_mnesia / c90c618
Reports root/ big
OK: 1486 / Failed: 0 / User-skipped: 393 / Auto-skipped: 0

ldap_mnesia_22 / ldap_mnesia / c90c618
Reports root/ big
OK: 1486 / Failed: 0 / User-skipped: 393 / Auto-skipped: 0

ldap_mnesia_23 / ldap_mnesia / c90c618
Reports root/ big
OK: 1486 / Failed: 0 / User-skipped: 393 / Auto-skipped: 0

pgsql_mnesia_22 / pgsql_mnesia / c90c618
Reports root/ big
OK: 3064 / Failed: 0 / User-skipped: 211 / Auto-skipped: 0

pgsql_mnesia_24 / pgsql_mnesia / c90c618
Reports root/ big
OK: 3064 / Failed: 0 / User-skipped: 211 / Auto-skipped: 0

mysql_redis_24 / mysql_redis / c90c618
Reports root/ big
OK: 3047 / Failed: 1 / User-skipped: 228 / Auto-skipped: 0

s2s_SUITE:both_tls_required:simple_message

{error,
  {timeout_when_waiting_for_stanza,
    [{escalus_client,wait_for_stanza,
       [{client,<<"alice_simple_message_73.82377@fed1/res1">>,
          escalus_tcp,<0.2606.2>,
          [{event_manager,<0.2602.2>},
           {server,<<"fed1">>},
           {username,<<"alice_simple_message_73.82377">>},
           {resource,<<"res1">>}],
          [{event_client,
             [{event_manager,<0.2602.2>},
            {server,<<"fed1">>},
            {username,<<"alice_simple_message_73.82377">>},
            {resource,<<"res1">>}]},
           {resource,<<"res1">>},
           {username,<<"alice_simple_message_73.82377">>},
           {server,<<"fed1">>},
           {host,<<"localhost">>},
           {port,5242},
           {auth,{escalus_auth,auth_plain}},
           {wspath,undefined},
           {username,<<"alice_simple_message_73.82377">>},
           {server,<<"fed1">>},
           {host,<<"localhost">>},
           {port,5242},
           {password,<<"makota2">>},
           {stream_id,<<"a8614fd01712d37f">>}]},
        10000],
       [{file,
          "/home/circleci/app/big_tests/_build/default/lib/escalus/src/escalus_client.erl"},
        {line,136}]},
     {s2s_SUITE,'-simple_message/1-fun-0-',2,
       [{file,"/home/circleci/app/big_tests/tests/s2s_SUITE.erl"},
        {line,124}]},
     {escalus_story,story,4,
       [{file,
          "/home/circleci/app/big_tests/_build/default/lib/escalus/src/escalus_story.erl"},
        {line,72}]},
     {test_server,ts_tc,...

Restructure the documentation #3259

Restructure the documentation #3259

Conversation

gustawlippa commented Sep 10, 2021 • edited Loading

NelsonVides left a comment

Choose a reason for hiding this comment

NelsonVides commented Sep 16, 2021

gustawlippa commented Sep 16, 2021 • edited Loading

NelsonVides Sep 16, 2021

Choose a reason for hiding this comment

gustawlippa Sep 16, 2021

Choose a reason for hiding this comment

gustawlippa Sep 16, 2021

Choose a reason for hiding this comment

chrzaszcz left a comment

Choose a reason for hiding this comment

chrzaszcz Sep 17, 2021 • edited Loading

Choose a reason for hiding this comment

gustawlippa Sep 17, 2021 • edited Loading

Choose a reason for hiding this comment

chrzaszcz Sep 17, 2021 • edited Loading

Choose a reason for hiding this comment

gustawlippa Sep 17, 2021

Choose a reason for hiding this comment

chrzaszcz left a comment

Choose a reason for hiding this comment

mongoose-im commented Sep 17, 2021 • edited Loading

codecov bot commented Sep 17, 2021 • edited Loading

Codecov Report

NelsonVides left a comment

Choose a reason for hiding this comment

gustawlippa commented Sep 20, 2021

NelsonVides commented Sep 20, 2021

NelsonVides left a comment

Choose a reason for hiding this comment

gustawlippa commented Sep 10, 2021 •

edited

Loading

gustawlippa commented Sep 16, 2021 •

edited

Loading

chrzaszcz Sep 17, 2021 •

edited

Loading

gustawlippa Sep 17, 2021 •

edited

Loading

chrzaszcz Sep 17, 2021 •

edited

Loading

mongoose-im commented Sep 17, 2021 •

edited

Loading

codecov bot commented Sep 17, 2021 •

edited

Loading