Migration documentation

[nilshempelmann]

Time to brush up the documentation.

@Zeitsperre @tlvu: I suggest to move this chapter on components to the top level documentation

This: https://birdhouse-deploy.readthedocs.io/en/latest/birdhouse/components/README.html
to here: https://birdhouse2-docs.readthedocs.io/en/latest/list_apps/

Probably also the highlevel descriotion of deployment would be fitting into the toplevel documentation

Any thoughts?

[tlvu]

@nilshempelmann
By "move" do you mean put a link or a reference at the new place to point to the old place?

It's much easier for us to keep the doc in the same repo as the code so when we perform code change we also update the docs at the same time.

[nilshempelmann]

@tlvu : The Top-level birdhouse Documentation is now starting with the introduction of the different components: https://birdhouse2-docs.readthedocs.io/en/latest/
Which I think is the right place.

How to align with https://birdhouse-deploy.readthedocs.io/en/latest/birdhouse/components/README.html

[tlvu]

The Top-level birdhouse Documentation is now starting with the introduction of the different components: https://birdhouse2-docs.readthedocs.io/en/latest/

@nilshempelmann
This is what I see at https://birdhouse2-docs.readthedocs.io/en/latest/, the components are not listed.

Do you mean here https://birdhouse2-docs.readthedocs.io/en/latest/apps/ ?

How to align with https://birdhouse-deploy.readthedocs.io/en/latest/birdhouse/components/README.html

The list of components at https://birdhouse-deploy.readthedocs.io/en/latest/birdhouse/components/README.html also includes house-keeping components like the scheduler or monitoring. I think we should only mention WPS services?

So I think keep keeping a duplicate list as it is at https://birdhouse2-docs.readthedocs.io/en/latest/apps/ is fine. The name and description of services do not change that often, a duplicate list is fine.

If you think it's useful, we can simply indicate next to each service how they be deployed (meaning from the PAVICS docker-compose stack or from Ansible). Some services, might have both. This allows the user the choice.

Also the PAVICS or DACCS stack (DACCS is just a continuation of PAVICS) is federated here https://marbleclimate.com/node.html. So if someone starts a new node, if would be useful for them to join the federation.

Where do you suggest we mention this federation?

[nilshempelmann]

Yes right, the list of birds is not longer at the start page ;-).

Agree, that a doublication of components is fine and makes sence, since the two lists follow different logics.

I added the initiatives in the current PR where Pavics, Daccs is mentioned. Marple can be added there as well and other initiatives I am not aware of.

[nilshempelmann]

@cehbrecht :
Should the birdhouse-workshop be integrated into the new birdhouse documentation? https://birdhouse.readthedocs.io/projects/workshop/en/latest/pywps.html

[cehbrecht]

@nilshempelmann I would keep the "workshop" docs separate. If we want a new one we could make it maybe with "jupyter books" and based on notebooks: https://jupyterbook.org/en/stable/intro.html

[Zeitsperre]

@nilshempelmann Thanks for making these changes, I like the look of the new site.

I agree that since this is simply a listing of the available kinds of services that can be deployed, we can probably be fine with pointing to the GitHub repositories and docker images.

I am a bit confused about whether we are showcasing the actual running services (i.e. the service endpoints) or simply the codes/docker images that users can leverage to build their own offerings.

When it comes to synchronization of documentation, I would love to be able to add URLs back to the parent birdhouse project in all the components, e.g.

[project.urls]
"Homepage" = "https://finch.readthedocs.io"
"About Birdhouse" = "https://new-birdhouse-docs.readthedocs.io"

Any idea when we want to go live with this?