Documentation topics

[rhfogh]

Having a code camp for improving Documentation was discussed at the last code camp, and again at today's (20231025) MXCuBEWeb meeting. The discussion seems to favour both writing overview documentation, and looking at the Sphinx documentation autogenerated from doc strings. One proposal was to use the structure presented in https://diataxis.fr/ to organise the documentation, though it is not clear how architectural documentation would fit into this paradigm.

Anyway, this issue is to collect proposals what what needs documenting, and who could volunteer to rite some of it - we need to share out the work. Proposals should say clearly whether they refer to mxcubecore, mxcubeweb, or mxcubeqt.

[rhfogh]

Proposed topics. These all fall into 'architectural documentation, explainining high-level organisation and salient points

• The system of Abstract Classes and how to use them (mxcubecore)
• Configuration with xml and yaml, and how to access the result (mxcubecore)
• Pydantic and exported methods (mxcubecore)
• Key signals connecting mxcubecore and UI (mxcubecore, mxcubeweb, mxcubeqt)
• The organisation and data structures of the queue, including conventions for what is contained in what (mxcubecore, mxcubeweb, mxcubeqt)

[fabcor-maxiv]

Maybe something about installation/deployment of mxcube(web) into production. The intention should not be to dictate or recommend one process but rather to give some pointers and maybe offer at least one simple solution that is known to work for simple cases without going into the details (which could be more or less a copy/paste of the instruction steps for the dev/demo environment). I assume every facility has the knowledge of how to install Python and Node.js things (there is no big mystery), and also each facility has its own quirks and way of doing things anyway.

[fabcor-maxiv]

https://board.net/p/MxCubeDocCamp

[rhfogh]

Superseded by the actual code camp