You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The below is written against #548 which made some rationalisations, prior to that it is likely even worse.
Some additional comments about the documentation - I think it's still confusing, partly the fault of python copier template. Perhaps in future we should just ignore most of their documentation templates because I think they are not really designed for our use case.
So, if you go to the documentation front page, to look for how to deploy mx-bluesky/hyperion you see this:
ok, so go to the "User Guide"
under installation, this doesn't mention dls_dev_env.sh.
the real documentation is in mx-bluesky/build/html/developer/general/how-to/get-started.html
I think we should delete the installation documentation in the User Guide as generally users won't be installing mx-bluesky themselves either as a development install or a production deployment.
Similarly "Run in a container"
In fact, maybe we should just get rid of the User Guide section entirely as there is nothing in there at the moment for actual users.
Ok, so how about the Developer Guide:
Maybe we should change the title of General MX-Bluesky Developer Guide so we don't have two of them...
So lets try General MX-Bluesky Developer Guide (the first one):
If I'm a developer, the install documentation must be in Developer Install? Wrong!
That's just the generic install documentation
Try Get started with mx-bluesky - at least this tells you to use dls_dev_setup.sh. But wait - it's really called dls_dev_env.sh.
How about General MX-Bluesky Developer Guide (second one)
Under Development Installation this is the same information but at least tells you to use the right script.
There's also this weird section called "hyperion" which is second in the TOC but is actually the introductory overview of the old hyperion project and should really be at the top-level to describe the difference between the mx-bluesky and hyperion portions and also it could probably do with some updating.
We should also combine the running the unit test sections from both halves as it's really one project with different ways of deploying and launching.
tl;dr
Get rid of User Guide section and move everything up one level, or at least clear it out until we have some documentation for actual users.
Rename "General MX-Bluesky Developer Guide" to something like"Hyperion Developer Guide"
Move and update the project overview from inside Hyperion section to the top level
Update the general developer install and unit test instructions and remove the duplicated hyperion ones
The text was updated successfully, but these errors were encountered:
The below is written against #548 which made some rationalisations, prior to that it is likely even worse.
Some additional comments about the documentation - I think it's still confusing, partly the fault of python copier template. Perhaps in future we should just ignore most of their documentation templates because I think they are not really designed for our use case.
So, if you go to the documentation front page, to look for how to deploy mx-bluesky/hyperion you see this:
ok, so go to the "User Guide"
under installation, this doesn't mention
dls_dev_env.sh
.the real documentation is in mx-bluesky/build/html/developer/general/how-to/get-started.html
I think we should delete the installation documentation in the User Guide as generally users won't be installing mx-bluesky themselves either as a development install or a production deployment.
Similarly "Run in a container"
In fact, maybe we should just get rid of the User Guide section entirely as there is nothing in there at the moment for actual users.
Ok, so how about the Developer Guide:
Maybe we should change the title of General MX-Bluesky Developer Guide so we don't have two of them...
So lets try General MX-Bluesky Developer Guide (the first one):
If I'm a developer, the install documentation must be in Developer Install? Wrong!
That's just the generic install documentation
Try Get started with mx-bluesky - at least this tells you to use
dls_dev_setup.sh
. But wait - it's really calleddls_dev_env.sh
.How about General MX-Bluesky Developer Guide (second one)
Under Development Installation this is the same information but at least tells you to use the right script.
There's also this weird section called "hyperion" which is second in the TOC but is actually the introductory overview of the old hyperion project and should really be at the top-level to describe the difference between the mx-bluesky and hyperion portions and also it could probably do with some updating.
We should also combine the running the unit test sections from both halves as it's really one project with different ways of deploying and launching.
tl;dr
The text was updated successfully, but these errors were encountered: