Documentation Review and Suggestions

[ashmeigh]

This pull request focuses on the comprehensive restructuring and updating of the "mdanse" documentation. The primary objective is to align the documentation with the Diataxis framework, resulting in a more organized, user-friendly, and modular structure.

Changes Made:

Introduction of Diataxis Framework:

Introduced the Diataxis framework, which features the following core sections:
Explanations
Tutorials
How-To Guides
Technical References
Each section serves a distinct purpose and follows a consistent and standardized structure.
Content Migration and Reorganization:

Migrated and meticulously reorganized the existing documentation content into their respective Diataxis sections.
Ensured a seamless transfer of essential information from the old documentation to the new structure, maintaining alignment with the framework.

Essential Content Updates:
Implemented essential updates to the existing content:
Removed outdated GUI (Graphical User Interface) as it's no longer relevant to the project.
Updated all references to Python 3 to ensure compatibility with modern Python versions.
Replaced outdated file format references with "HDF" (Hierarchical Data Format) to reflect contemporary data storage practices.

Expected Benefits:

Improved documentation organization for streamlined access to explanations, tutorials, how-to guides, and technical references.
Alignment with contemporary software practices, ensuring compatibility with modern Python and data storage standards.
Enhanced clarity, relevance, and usability of the documentation.

Checklist:

Documentation structure and content have been successfully updated.
Tutorials have been planned and created.
How-to guides have been fully created.
Essential changes to explanations have been implemented.
The new "Technical References" section has been introduced.

[MBartkowiakSTFC]

@ashmeigh What output did you get when you built the documentation? It seems that quite a few errors and warnings are still triggered when I build it on my computer.

documentation_build_output.txt

[MBartkowiakSTFC]

Definitely don't put any numbers in the title of a section. It's up to the documentation engine to assign numbers. Now if you move this text segment, the number will be wrong.

[MBartkowiakSTFC]

Same problem here: the number should not be included in the text.

[MBartkowiakSTFC]

This label should, if possible, refer to the contents of the text and not number of the section.

[MBartkowiakSTFC]

The file name contains a space, and in a very awkward location, directly before the extension. Please rename.

[MBartkowiakSTFC]

This kind of list really should use automatic numbering.

[MBartkowiakSTFC]

This change was clearly NOT meant to happen. The MMTK name has to stay here, as this is the explanation of the origins of MDANSE.

[MBartkowiakSTFC]

Closes #10 #11

[MBartkowiakSTFC]

Thank you for the changes! The structure of the documentation is much better now.