search

mxcube / mxcubecore

Backend used by MXCuBE
http://mxcube.github.io/mxcube/
GNU Lesser General Public License v3.0
11 stars 51 forks source link

Add document about the documentation system #909

Closed fabcor-maxiv closed 3 months ago

fabcor-maxiv commented 3 months ago

GitHub: related to https://github.com/mxcube/mxcubeweb/pull/1177

fabcor-maxiv commented 3 months ago

The first part is taken from https://github.com/mxcube/mxcubeweb/pull/1177.

We should try to avoid duplicates like this. Maybe if it is not specific to Web or Qt then it should be placed in core. Web and Qt could simply link back to core.

axelboc commented 3 months ago

We should try to avoid duplicates like this. Maybe if it is not specific to Web or Qt then it should be placed in core. Web and Qt could simply link back to core.

One doc site? One monorepo? :grin:

fabcor-maxiv commented 3 months ago

We should try to avoid duplicates like this. Maybe if it is not specific to Web or Qt then it should be placed in core. Web and Qt could simply link back to core.

One doc site? One monorepo? 😁

Not sure if it is a serious suggestion (at least partly). 1. Unified documentation: maybe that would be nice, I do not know, I have not considered it, seems like it would be some work. 2. Monorepo: having never worked with one (that I can remember) it is hard to judge, but I think I would be against it.

axelboc commented 3 months ago

Not sure if it is a serious suggestion (at least partly). 1. Unified documentation: maybe that would be nice, I do not know, I have not considered it, seems like it would be some work. 2. Monorepo: having never worked with one (that I can remember) it is hard to judge, but I think I would be against it.

Mostly joking since I have no clue what a monorepo looks like for a Python project :smile_cat:. In all seriousness, though, I do think it would hugely improve developer experience (one PR in the monorepo, instead of two PRs in two separate repos that have to be reviewed and merged together), and simplify dev ops (dev installation, testing, deployment, etc.). Monorepos are now very common for front-end projects, but that's because the tooling has improved sufficiently; no idea what the state is in the Python world. Either way, a monorepo would be a prerequisite to having a single doc site. Sorry for the huge tangent :sweat_smile:

marcus-oscarsson commented 3 months ago

I agree that we should definitely avoid duplication.

We moved a way from a monorepo solution using Git submodules a few years back because people struggled with the submodules. Moving back to some sort of monorepo would make some things easier but others harder so I think we should try to keep things as they are unless there some very good arguments for changing.

I think the way it is today works well enough, we could simply add links from the mxcubeweb documentation to the mxcubecore one. I think other solutions like having a separate repository for documentation risk to create unnecessary overhead and complicates things. We could perhaps use https://github.com/mxcube/mxcube for some common documentation and then link to that

axelboc commented 3 months ago

Yeah submodules aren't great. Front-end monorepos typically rely on a smart package manager (like pnpm) or some other dedicated tooling.