Merge pull request #9227 from wazuh/enhancement/idr560-create-llms-ready-documentation-4.9

Add Markdown files creation support 4.9

Author: javimed

Makefile

@@ -19,10 +19,11 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext markdown
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  markdown   to make Markdown files"
 	@echo "  html-prod  to make standalone HTML files, including GA code. Production only"
 	@echo "  html-dev   to make standalone HTML files, without GA code. Development only"
 	@echo "  html-quick to make standalone HTML files using parallel processing"
@@ -56,14 +57,20 @@ clean:
 
 theme:
 	@cd source/_themes/wazuh_doc_theme_v3 && npm run build-all
-	@echo 
+	@echo
 	@echo Build finished. The main theme assets has been updated.
 	@cd ../../..
 	@echo
 
 search-index:
 	npx -y pagefind@v1.1.0 --site $(BUILDDIR)/html --force-language en
 
+markdown:
+	$(SPHINXBUILD) -b markdown $(ALLSPHINXOPTS) $(BUILDDIR)/markdown
+	@echo
+	@echo "Build finished. The Markdown files are in $(BUILDDIR)/markdown."
+	@echo
+
 html-production:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -t production
 	@echo
@@ -80,17 +87,17 @@ html-quick:
 	$(SPHINXBUILD) -j auto -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-	
+
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 	@echo
 
 html-prod: html-production search-index
-	
+
 html-dev: html-development search-index
-	
+
 html-search: html search-index
 
 dirhtml:

requirements.txt

@@ -1,7 +1,8 @@
-Sphinx==7.2.6
+Sphinx==7.3.7
 sphinx-tabs==3.4.5
 docutils==0.18.1
 jsmin==3.0.1
 Jinja2==3.1.6
 Pygments==2.15.1
-sphinx-reredirects==0.1.5
+sphinx-reredirects==0.1.5
+sphinx-markdown-builder==0.6.9

source/conf.py

@@ -55,7 +55,8 @@
     'sphinx.ext.extlinks', # Sphinx built-in extension
     'sphinx_tabs.tabs',
     'wazuh-doc-images', # Custom extension
-    'sphinx_reredirects'
+    'sphinx_reredirects',
+    'sphinx_markdown_builder'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -148,7 +149,7 @@
                 current_release[0] == v3_release[0] and
                 current_release[1] < v3_release[1])
     html_theme_options['is_pre_v3'] = is_pre_v3
-    
+
     # Allow dark mode is set to false by default
     html_theme_options['include_mode'] = True
     # Allow switching between modes is set to false by default
@@ -241,7 +242,7 @@
 # Add link anchors for each heading and description environment. Default: True.
 html_permalinks = True
 
-# Text for link anchors for each heading and description environment. HTML entities 
+# Text for link anchors for each heading and description environment. HTML entities
 # and Unicode are allowed. Default: a paragraph sign; ¶
 html_permalinks_icon = ''
 
@@ -370,6 +371,10 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html', 'not_found.html']
 
+# -- Options for Markdown output --------------------------------------------
+
+# Options for sphinx-markdown-builder
+markdown_http_base = '' # Use relative links
 
 # -- Extension configuration -------------------------------------------------
 
@@ -435,7 +440,7 @@ def setup(app):
         os.mkdir(static_path_str)
 
     if html_theme == 'wazuh_doc_theme_v3':
-        
+
         # Download spec file if the file is missing or older that spec_max_age
         if api_tag != '' and apiURL != '':
             spec_max_age = 60*15 # 15 minutes
@@ -450,7 +455,7 @@ def setup(app):
             except FileNotFoundError:
                 print(server_api_spec_path + " not found")
                 download_needed = True
-            
+
             if download_needed == True:
                 print ('Downloading ' + 'spec-'+api_tag+'.yaml')
                 spec_path, url_retrieve_headers = urlretrieve(apiURL, server_api_spec_path)
@@ -633,16 +638,16 @@ def finish_and_clean(app, exception):
                     os.remove(mapFilePath)
                 except:
                     print("Error while deleting file : ", mapFilePath)
-            
+
             # Remove the source mapping URLs
             for assetsFilePath in assetsFiles:
                 try:
                     with open(assetsFilePath, "r") as f:
                         lines = f.readlines()
                     with open(assetsFilePath, "w") as f:
                         for line in lines:
-                            line = re.sub("//# sourceMappingURL=.*\.map", "", line)
-                            line = re.sub("/\*# sourceMappingURL=.*\.map \*/", "", line)
+                            line = re.sub(r"//# sourceMappingURL=.*\.map", "", line)
+                            line = re.sub(r"/\*# sourceMappingURL=.*\.map \*/", "", line)
                             f.write(line)
                 except:
                     print("Error while removing source mapping from file: ", assetsFilePath)