Add VSCode specific IDE documentation

[RasmiaKulan]

Progresses #2598

Description

Added VSCode IDE specific documentation detailing the:

• Set up of VSCode
• Required and recommended extensions for smoother workflow
• VSCode built in feature to Auto Save
• Debugging in Python
• Useful Keybinds

Developer Testing

• I have verified unit tests pass locally: python -m pytest -vs
• ...

Acceptance Criteria and Reviewer Testing

• Unit tests pass locally: python -m pytest -vs
• from the source directory, make build-docs
• cd docs/build/html
• python -m http.server 8000
• In a browser of your choosing, navigate to: http://0.0.0.0:8000/developer_docs/how-to-guides/testing.html (localhost:8000 worked for me)
• Validate that you can see all the instructions and all the links mentioned are correct.

Documentation and Additional Notes

[ashleymeigh2]

This is a helpful guide, but it doesn’t fully align with the expectations of a tutorial in the Diátaxis framework. Diátaxis defines four distinct types of documentation: tutorials (learning-oriented, step-by-step guidance), how-to guides (task-focused instructions), reference (factual, lookup-style information), and explanation (conceptual background and reasoning). In Diátaxis, a tutorial is meant to provide a clear, guided learning experience with a specific outcome, taking the reader step by step through a task so they can successfully achieve something concrete.

At the moment, the tutorial mixes several types of documentation. For example, the setup steps resemble a how-to guide, the extension lists read more like reference material, and some sections provide general explanation. While all of this information is useful, combining them in a single tutorial can make it less clear what the reader is expected to accomplish by the end.

If the goal is a tutorial, it should walk a new developer through a concrete scenario (e.g., “set up IDE for Mantid Imaging and run your first debug session”) with clear, sequential steps and expected results. Alternatively, the content could be split:
Setup steps → How-to guide
Extension list → Reference
VSCode features and workflows → Explanation

As it stands, the document feels like a general overview rather than a true tutorial, which makes it harder for users to follow or know what they’ll achieve by the end.

[RasmiaKulan]

I followed the style of the Mantid Documentation on VSCode for this. However, it does not follow the Diátaxis framework. @ashleymeigh2 and I have decided that once she adds the documentation for PyCharm, I would be able to get a better idea of the Diátaxis framework and could follow her footsteps for VSCode.

[ashleymeigh2]

I followed the style of the Mantid Documentation on VSCode for this. However, it does not follow the Diátaxis framework. @ashleymeigh2 and I have decided that once she adds the documentation for PyCharm, I would be able to get a better idea of the Diátaxis framework and could follow her footsteps for VSCode.

Thanks for the context that makes sense, especially if you were following the existing Mantid docs. I think setting an IDE belongs in the Getting Started tutorial as this should cover everything a developer needs to get up and running in one place so cloning the repo, setting up the environment, and getting an IDE ready to work in. That way, someone new can follow a single flow and end up in a position where they can start contributing. Idk whats your thoughts are about this?

[RasmiaKulan]

Thanks for the context that makes sense, especially if you were following the existing Mantid docs. I think setting an IDE belongs in the Getting Started tutorial as this should cover everything a developer needs to get up and running in one place so cloning the repo, setting up the environment, and getting an IDE ready to work in. That way, someone new can follow a single flow and end up in a position where they can start contributing. Idk whats your thoughts are about this?

As the content for this section exceeds what can be viewed without scrolling, @JackEAllen and I agreed that it should have its own page. If the content is reduced under the Diátaxis framework, I would be happy to include it as a continuation of the Getting Started tutorial.
Jack also mentioned adding an "IDE Setup" section, which I forgot to include in this PR. It could be useful to introduce this section with subheadings for "VSCode" and "PyCharm". Let me know if you think otherwise 😊

[JackEAllen]

Overall a really good start to adding some developer documentation guiding new developers through how to set up a VSCode environment to get up and running with Mantid Imaging as a contributor! What you have written is clear and easy to follow.

I've left a few suggestions, some of which may be irrelevant depending on the eventual format this documentation becomes to be in-line with Diátaxis as per @ashleymeigh2 comments. You can read more about Diátaxis HERE.

The general gist is that the framework is composed of 4 quadrants in which documentation can be roughly categorised / split under (there can be overalap: Tutorials, How-to guides, Reference, and Explanation.

I think what @ashleymeigh2 is stating here is that the documentation you have so far could technically be split into 2-3 of these sections: how-to for Prerequisites, getting started, configuring debugging, auto-save; reference for the full extensions table with descriptions and also the keybindings and optionally (probably recommended a tutorial for debugging - maybe "how to debug your first test" or similar for varying types of tests or bugs (unit test, system test and a simply bug).

I'd maybe write up. separate issue for such as tutorial though. In addition to Diátaxis, something to always bear in mind for how-to and tutorial sections is that everyone learns in different ways so when it makes sense too, adding screenshots and recordings can be useful and is something we should do more of in general for inclusivity purposes.

[JackEAllen]

This should probably be a hyperlink to VSCode

[JackEAllen]

Maybe reword to: "A Mantid Imaging developer environment (See getting-started guide)"

[JackEAllen]

If sticking to this format of a tutorial, consider changing this too (See Extensions) and link to the sub-header

[JackEAllen]

We can probably drop this sentence as this is more of a responsibility of the maintainers to describe if a package is only compatible for certain OS's. In theory, all VSCode extensions are OS agnostic

[JackEAllen]

May be worth either dropping this one or only loosely recommending Jupyter Notebook usage for Mantid Imaging development is quite rare and usually only useful for R&D or testing CIL

[JackEAllen]

I'd maybe suggest if this stays in a tutorial or how-to guide that we consider adding a few step-by-step screenshots or small screen recording / GIF snapshots of the debugging steps.

[JackEAllen]

I'd recommend adding this extension as a recommendation too with the move over to pixi: https://marketplace.visualstudio.com/items?itemName=renan-r-santos.pixi-code

[ashleymeigh2]

This is a really strong piece of documentation. it's clear, easy to follow, and the addition of GIFs makes it much more accessible. The restructuring towards the Diátaxis framework is definitely moving things in the right direction.

In terms of structure, the split into How-to guides and Reference works well. The task-based sections (opening VSCode, selecting the interpreter, enabling auto-save) read naturally as how-to content, while the extensions and keybindings fit well as reference material. This is a good alignment with Diátaxis overall.

One thing I’d still question is where this content sits in the wider documentation. A Getting Started tutorial should ideally include everything a new developer needs to begin working cloning the repo, setting up the environment, and getting an IDE ready to use. At the moment, that flow feels slightly incomplete without a basic IDE setup step. Because of that, the core VSCode setup (opening the project and selecting the interpreter) would fit well in Getting Started, with this page focusing on additional workflows and tooling.

On debugging, I don’t think this belongs in a general VSCode setup/tutorial page. It feels more appropriate as part of a dedicated debugging section or a separate how-to/tutorial focused specifically on debugging workflows (e.g. “how to debug your first test”). This keeps concerns separated and makes it easier for users to find what they need at the right time.

In terms of relevance to Mantid Imaging, some parts of this page are clearly project-specific, such as selecting the mantidimaging-dev Python interpreter, opening and working within the Mantid Imaging repository, and running tests in that context. These are the most important elements to prioritise. Other parts, like opening a project in VSCode, using the command palette, or enabling auto-save, are useful for new developers but are more general and not unique to Mantid Imaging, so they should be kept concise and framed within the project context. There are also sections that are not particularly Mantid-specific, such as large extension lists (especially general-purpose ones), detailed extension descriptions, keybindings tables, and general VSCode feature explanations. While not incorrect to include, these make the page feel more like a general VSCode guide, so it may be worth trimming or moving them to a reference section to keep the focus on what is most relevant for Mantid Imaging developers.

A few smaller points: linking to VSCode directly is a nice improvement, rewording the prerequisites makes them clearer, and internal links (e.g. to the extensions section) will help navigation. The note about extension OS compatibility can likely be removed, and the comment about Jupyter being rarely used is worth considering.

Overall, this is in a really good place just needs a bit of refinement around where certain content lives and how focused it is on the Mantid Imaging developer experience.

[JackEAllen]

This is looking really good. Thank you for adding this. I think it will be really helpful for anyone new joining the project. I do have a few minor suggestions to improve clarity in a few areas and also some nitpicks which are you welcome to ignore if you disagree.

[JackEAllen]

NITPICK, we can probably condense this slightly by linking the topics directly:

Suggested change

	1. An installed copy of VSCode - `Download here <https://code.visualstudio.com/download>`_
	2. A clone of the Mantid Imaging repository - `GitHub link <https://github.com/mantidproject/mantidimaging>`_
	3. A configured Mantid Imaging developer environment (See :ref:`getting-started` guide)
	1. An installed copy of `VSCode <https://code.visualstudio.com/download>`_
	2. A clone of the `Mantid Imaging repository <https://github.com/mantidproject/mantidimaging>`_
	3. A configured Mantid Imaging developer environment (See :ref:`getting-started` guide)

[JackEAllen]

NITPICK: i'd be tempted to place Ctrl+Shift+P in an inline code block to highlight its a command

[JackEAllen]

NITPICK: The inline code block for the path example ("...\\AppData\\Local\\miniforge3\\envs\\mantidimaging-dev\\python.exe") doesn't quite format nicely for me in the built Sphinx docs, in that it is across two lines, maybe consider placing in a dedicated code block if you also experience this and agree that it would look nicer?

`"...\\AppData\\Local\\miniforge3\\envs\\mantidimaging-dev\\python.exe"`

[JackEAllen]

It may also be worth mentioning that if using Pixi, interpreters can be found automatically via the .pixi folder in the project root where the Pixi equivalent interpreter path would be something like: Python 3.12.12 (dev) ./.pixi/envs/dev/bin/python and that more information about Pixi VSCode setup can be found HERE

[JackEAllen]

NITPICK: For consistency, i'd recommend including the command for doing this again. Also, by default for me, in a fresh vscode instance, `launch.json after installing the python debugger module has a pretty empty structure:

{
  "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Debugger: Current File",
            "type": "debugpy",
            "request": "launch",
            "python": "${file}",
            "console": "integratedTerminal",
        },
    ]
}

I believe setting the "type" to "python" may be deprecated and that "debugpy" may be the preferred type going forward

When working over ssh where no GUI is present, it may be worth recommending addition environment setup to set "QT_QPA_PLATFORM": "offscreen" and also "MPLBACKEND": "Agg"

An example setup for me over ssh for unit tests only looks like this for example if this is helpful:

        {
            "name": "Headless: All Unit Tests",
            "type": "debugpy",
            "request": "launch",
            "python": "${workspaceFolder}/.pixi/envs/dev/bin/python",
            "module": "pytest",
            "console": "integratedTerminal",
            "args": [
                "--run-unit-tests",
                "-pno:django",
                "${workspaceFolder}/mantidimaging"
            ],
            "env": {
                "QT_QPA_PLATFORM": "offscreen",
                "MPLBACKEND": "Agg"
            },
            "presentation": {
                "hidden": false,
                "group": "Mantid Imaging",
                "order": 3
            }
        },

[JackEAllen]

NITPICK: if you agree, maybe it would be clearer to include an entire configuration in this example and separately isolate the proposed env block for headless running (this will only work for tests) as this is more of an optional thing depending on whether your working with a GUI of not

[JackEAllen]

I would be tempted to include a link to the VScode debugger docs somewhere to make it easier for someone reading this to know where to learn more about how the debugger works