Add Sphinx script to build documentation.

Fix minor issues in markdown documents and group them im `toctree`
directives. Then use `myst-parser` to parse markdown files.

To build documentation:
* pip install -r doc/requirements.txt
* make -C doc html

Refs #1419

Author: reznikmm

doc/.gitignore

@@ -0,0 +1,2 @@
+_build
+ada_language_server.wiki

doc/HACKING.md

@@ -148,7 +148,7 @@ The UI offers ways to run or debug one test, a subset of tests or all tests.
 
 ### Other tests
 
-See more about the project testsuite [here](../testsuite/README.md).
+See more about the project testsuite [here](https://github.com/AdaCore/ada_language_server/blob/master/testsuite/README.md).
 
 ## Release VS Code extension
 

doc/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile ada_language_server.wiki
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+ada_language_server.wiki:
+	git clone --depth=1 https://github.com/AdaCore/ada_language_server.wiki.git

doc/README.md

@@ -18,13 +18,13 @@ You can also use custom commands to perform queries on the code base, to develop
 
 Here are some implementations of custom features in the ALS implemented through this mechanism:
 
-* [Show Dependencies](../source/ada/lsp-ada_handlers-show_dependencies_commands.ads)
-* [Other File](../source/ada/lsp-ada_handlers-other_file_commands.ads)
+* [Show Dependencies](https://github.com/AdaCore/ada_language_server/blob/master/source/ada/lsp-ada_handlers-show_dependencies_commands.ads)
+* [Other File](https://github.com/AdaCore/ada_language_server/blob/master/source/ada/lsp-ada_handlers-other_file_commands.ads)
 
 ## Feature description document
 
 Each feature is described in a dedicated Markdown document.
-There is [a list of all features](.#list-of-features) at the end of this document.
+There is [a list of all features](#list-of-custom-features) at the end of this document.
 We provide a [template](./TEMPLATE.md) for convenience.
 The feature description document has the following structure:
 
@@ -62,3 +62,32 @@ related resources.
  * [Check Syntax](check_syntax.md)
  * [Executables](executables.md)
  * [Call Hierarchy](callhierarchy.md)
+ * [Document symbol params](document_symbol_params.md)
+ * [Get project attribute value](get_project_attribute_value.md)
+ * [Initialization](initialization.md)
+ * [Object dir](object_dir.md)
+ * [Project file](project_file.md)
+ * [Source dirs](source_dirs.md)
+ * [Workspace symbol params](workspace_symbol_params.md)
+
+```{toctree}
+:maxdepth: 1
+:caption: "List of custom features:"
+:hidden:
+
+debug
+other_file
+reference_kinds
+show_dependencies
+check_syntax
+executables
+callhierarchy
+document_symbol_params
+get_project_attribute_value
+initialization
+object_dir
+project_file
+source_dirs
+workspace_symbol_params
+TEMPLATE
+```

doc/conf.py

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Ada & SPARK extension for VS Code"
+project_copyright = "2024-2025, AdaCore"
+author = "AdaCore"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+]
+
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    # 'ada_language_server.wiki/Custom-colors-in-VS-Code.md',
+    # 'ada_language_server.wiki/Getting-Started.md',
+    "ada_language_server.wiki/Home.md",
+    # 'ada_language_server.wiki/Project-file-editing.md',
+    # 'ada_language_server.wiki/Set-workspace-specific-environment-variables.md',
+    "ada_language_server.wiki/Supported-LSP-requests.md",
+    # 'ada_language_server.wiki/Working-on-a-remote-machine.md',
+    # 'build.md',
+    "gitpod.md",
+    "protocol.md",
+    "specification-3-14.md",
+    "specification-3-15.md",
+    "specification-3-16.md",
+]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+
+myst_heading_anchors = 3

doc/executables.md

@@ -20,7 +20,7 @@ We introduce two commands, the first one:
 
 Which provides the mains for the project, with a response type:
 
-```typesript
+```typescript
 type GlsMainResult = string[];
 ```
 
@@ -30,6 +30,6 @@ The second one is:
 
 Which provides the executables for the project, with a response type:
 
-```typesript
+```typescript
 type GlsExecutableResult = string[];
 ```

doc/index.rst

@@ -0,0 +1,20 @@
+.. Ada & SPARK extension for VS Code documentation master file, created by
+   sphinx-quickstart on Thu Dec 26 19:26:17 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Ada & SPARK extension for VS Code documentation
+===============================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   Tutorial: Using Ada in VS Code <ada_language_server.wiki/Getting-Started.md>
+   refactoring_tools
+   settings
+   traces
+   tips_and_tricks
+   build
+   Developing on the Ada Language Server <HACKING.md>
+   Protocol extensions <README.md>

doc/object_dir.md

@@ -16,8 +16,8 @@ type ObjDirResponse = string;
 
 And a new command with out arguments:
 
-  method: `als-object-dir`
+    method: `als-object-dir`
 
 Returning the project file of the loaded project like this:
 
-  result: `ObjDirResponse`
+    result: `ObjDirResponse`

doc/project_file.md

@@ -15,8 +15,8 @@ export type ProjectFileResponse = string; // The Path to the GPR project file
 
 And a new command with out arguments:
 
-  command: `als-project-file`
+    command: `als-project-file`
 
 Returning the project file of the loaded project like this:
 
-  result: `ProjectFileResponse`
+    result: `ProjectFileResponse`

doc/refactoring_tools.md

@@ -27,7 +27,7 @@
 
 [Source](https://github.com/AdaCore/ada_language_server/blob/master/source/ada/lsp-ada_handlers-named_parameters_commands.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/named_parameters/)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/named_parameters/)
 
 ![named_parameters](https://user-images.githubusercontent.com/22893717/166944482-cfebab94-adf8-4de5-9018-8415be94f8f5.gif)
 
@@ -44,7 +44,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-subprogram_signature.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/add_parameter/)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/add_parameter/)
 
 ![add_parameter](https://user-images.githubusercontent.com/22893717/166926928-f6f5243c-6008-435f-9c2f-40aec0517936.gif)
 
@@ -58,7 +58,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-subprogram_signature-remove_parameter.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/remove_parameter)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/remove_parameter)
 
 ![remove parameter](https://user-images.githubusercontent.com/22893717/166926891-d621fb59-8524-4ba8-abfc-74c12fed2adf.gif)
 
@@ -72,7 +72,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-subprogram_signature.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/move_parameter)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/move_parameter)
 
 ![move_parameter](https://user-images.githubusercontent.com/22893717/166927234-ba038012-25be-476e-bd29-d85c10a5b2d3.gif)
 
@@ -85,7 +85,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-subprogram_signature.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/change_parameter_mode)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/change_parameter_mode)
 
 ![change_parameter_mode](https://user-images.githubusercontent.com/22893717/166927346-cbaa9789-eb44-44df-8a9a-c2b770d3a93e.gif)
 
@@ -99,7 +99,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-subprogram_signature-change_parameters_type.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/change_parameter_type)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/change_parameter_type)
 
 ![change_parameter_type](https://user-images.githubusercontent.com/22893717/166927382-b04c5415-dc3e-49e1-9ef3-2840579447d8.gif)
 
@@ -113,7 +113,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-subprogram_signature-change_parameters_default_value.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/change_parameter_default_value)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/change_parameter_default_value)
 
 ![change_parameter_default_value](https://user-images.githubusercontent.com/22893717/166927617-f6f33bc4-d660-44ce-b836-bf02b839887e.gif)
 
@@ -128,7 +128,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-extract_subprogram.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/extract_subprogram)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/extract_subprogram)
 
 ![extract_subprogram](https://user-images.githubusercontent.com/22893717/166927664-c61af27f-a446-4e3a-acbe-71b7fa88e925.gif)
 
@@ -141,7 +141,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-pull_up_declaration.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/pull_up_declaration)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/pull_up_declaration)
 
 ![pull_up_declaration](https://user-images.githubusercontent.com/22893717/166927695-e6b9e016-1374-4aa5-9640-60aaf1a4b7fe.gif)
 
@@ -155,7 +155,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-suppress_separate.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/suppress_separate)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/suppress_separate)
 
 ![suppress_separate](https://user-images.githubusercontent.com/22893717/166927780-441fdb3f-271f-4f69-99ff-367e8eef301e.gif)
 
@@ -169,7 +169,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-introduce_parameter.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/introduce_parameter)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/introduce_parameter)
 
 ![introduce parameter](https://user-images.githubusercontent.com/22893717/181477996-564a1365-33df-4227-bb82-e9ed802b4ed0.gif)
 
@@ -181,7 +181,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-replace_type.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/replace_type)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/replace_type)
 
 ![replace type](https://user-images.githubusercontent.com/22893717/217803466-ae5500fe-a071-4fe9-a669-24cd9c82917a.gif)
 
@@ -193,7 +193,7 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/edge/src/lal_refactor-auto_import.adb)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/auto_import)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/auto_import)
 
 ![auto import](https://user-images.githubusercontent.com/22893717/217804710-e686ef22-227b-4e81-8bb1-1f218e5709df.gif)
 
@@ -205,6 +205,6 @@
 
 [Source](https://github.com/AdaCore/lal-refactor/blob/main/src/lal_refactor-sort_dependencies.ads)
 
-[Demo Source](../integration/vscode/Code%20Samples/refactoring_demos/sort_dependencies)
+[Demo Source](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/Code%20Samples/refactoring_demos/sort_dependencies)
 
 ![replace type](https://user-images.githubusercontent.com/22893717/217805066-ee69e6d6-4c9e-4075-8eb6-1fca7793c428.gif)