Documentation on readthedocs.io

jordisala1991 commented 3 years ago

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:

[x] Create all projects on readthedocs.io
[x] Create a main project (it could be dev-kit)
[x] Assign all projects as a subproject of the main one
[x] 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
[x] Ensure that docs for all projects works
[x] Update READMES to point to new docs
[x] Redirect the website pages related to docs to this new doc
[x] 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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

Now we're moving the doc to https://docs.sonata-project.org/en/master/ And we're planning to move the translations (https://github.com/sonata-project/dev-kit/issues/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 commented 3 years ago

Done, all documentation redirected. This can be closed.

VincentLanglet commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

jordisala1991 commented 3 years ago

I will prepare redirects for article bundle, they werent done

jordisala1991 commented 3 years ago

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

sonata-project / dev-kit

Documentation on readthedocs.io #1613