Documentation on readthedocs.io

[jordisala1991]

Current situation:

• Old website that is outdated and hosts docs, demo and "marketing" pages
• Website is not always up, currently missing SSL certificates
• Design of the docs is lacking some features that we have to implement ourselves
• The overall design of the current sonata-project.org page looks old.

Desired situation:

• Website only as a marketing tool (maybe only a landing page)
• Docs separate and built with a template (https://sphinx-themes.org/)
• Demo using its own subdomain and with a copy of Sandbox, for testing purposes

Why is better than before?

• We don't need to "improve" the styles for the docs, we are using a theme that is constantly getting updates
• We don't rely on our own hosting for docs, which is nice, because it will have more uptime
• Less efforts on maintaining up to date the website, we just need a design for a one page, not a whole website
• We can modify easily pages like "getting started with sonata", actually this page contains really old instructions because they are not easily modifiable

How do we get there:

• Create all projects on readthedocs.io
• Create a main project (it could be dev-kit)
• Assign all projects as a subproject of the main one
• Add the main documentation (it could be one or 2 pages) to the main project, with links to the subprojects and some general info like getting started
• Ensure that docs for all projects works
• Update READMES to point to new docs
• Redirect the website pages related to docs to this new doc
• Point a custom domain on readthedocs for better SEO. (this is optional)

TL;DR: We are trying to move the documentation to readthedocs.io.

There could be more things to be done.

[core23]

Maybe we could add a bonus feature:

• Add a blog system for project updates. This can be done with simple Markdown files. Something like doctrine or easy admin

[jordisala1991]

All projects are created and all branches assigned. They are configured and added @VincentLanglet as a maintainer (is the only one with account on readthedocs AFAIK).

The ones I couldn't add were, some lower branches that are not maintained and:

• SonataCoreBundle (we don't care because it is deprecated)
• SonataEasyExtendsBundle (we don't care because it is deprecated)
• SonataPropelBundle (we don't care...)

Now we need to check if everything work (I know there are some hardcoded links to the sonata-project page)
and add a main documentation page on dev-kit.

Once all that is done we can start modifying the READMEs

[VincentLanglet]

As a first step, we could add all the documentation link (like https://sonata-project.readthedocs.io/projects/SonataAdminBundle) to the page https://sonata-project.readthedocs.io

Next, we'll have to point https://sonata-project.org/ to https://sonata-project.readthedocs.io/

[core23]

As a first step, we could add all the documentation link (like https://sonata-project.readthedocs.io/projects/SonataAdminBundle) to the page https://sonata-project.readthedocs.io

What's the source repo for the landing page (https://sonata-project.readthedocs.io)?

[VincentLanglet]

What's the source repo for the landing page (https://sonata-project.readthedocs.io)?

dev-kit.

We need to create a /doc/index.rst file in dev-kit repository.

[VincentLanglet]

Now we're moving the doc to https://docs.sonata-project.org/en/master/
And we're planning to move the translations (#1614)

Can we agree about the future of https://github.com/sonata-project/sonata-project.org ? (Maybe in another issue)
https://sonata-project.org/ should just because an homepage IMHO, maybe it's easier to start from scratch

[jordisala1991]

Done, all documentation redirected. This can be closed.

[VincentLanglet]

Should we still update the doc to change the url

https://sonata-project.org/bundles/doctrine-orm-admin/master/doc/index.html

to the readthedocs.io one ?

like in https://github.com/sonata-project/SonataAdminBundle/blob/4.x/docs/getting_started/installation.rst

what is the preferred url to use ?

[jordisala1991]

Yes, those urls can be changed. They should work because of redirects, but better to not rely on them so much. Can you do the Pr?

[VincentLanglet]

Sure
sonata-project/SonataAdminBundle#7435
sonata-project/SonataDoctrineORMAdminBundle#1506
sonata-project/SonataDoctrineMongoDBAdminBundle#642
sonata-project/SonataUserBundle#1390
sonata-project/SonataArticleBundle#301
sonata-project/SonataClassificationBundle#710
sonata-project/SonataCommentBundle#315
sonata-project/SonataTranslationBundle#526
sonata-project/SonataTimelineBundle#379
sonata-project/SonataPageBundle#1338
sonata-project/SonataNotificationBundle#606
sonata-project/SonataNewsBundle#753
sonata-project/SonataIntlBundle#448
sonata-project/SonataDoctrinePhpcrAdminBundle#715
sonata-project/SonataDashboardBundle#321

There is also an issue with this redirect:
https://sonata-project.org/bundles/article/master/doc/index.html

[jordisala1991]

I will prepare redirects for article bundle, they werent done

[jordisala1991]

I just asked rande to apply the redirects for article bundle.