diff --git a/Makefile b/Makefile index ff8d889..d9ab8f0 100644 --- a/Makefile +++ b/Makefile @@ -23,15 +23,15 @@ clean: # Catch-all target: route all unknown targets to Sphinx using the new "make mode" option. # $(O) is meant as a shortcut for $(SPHINX_OPTS). doc-%: - @$(SPHINX_BUILD) -M $* "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINX_OPTS) $(O) -a -t Partners + @$(SPHINX_BUILD) -M $* "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINX_OPTS) $(O) -a -t Partners -j 8 -docs: doc-markdown +docs: doc-markdown doc-singlemarkdown test-diff: - @echo "Building markdown..." - @$(SPHINX_BUILD) -M markdown "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINX_OPTS) $(O) -a -t Partners -j 8 + @echo "Building docs..." + @$(MAKE) docs @echo "Building markdown with configuration overrides..." @$(SPHINX_BUILD) -M markdown "$(SOURCE_DIR)" "$(BUILD_DIR)/overrides" $(SPHINX_OPTS) $(O) -a \ @@ -39,9 +39,15 @@ test-diff: -D markdown_docinfo=1 -D markdown_anchor_sections=1 -D markdown_anchor_signatures=1 \ -D autodoc_typehints=signature -D markdown_bullet=- -D markdown_flavor=github + @echo "Building singlemarkdown llms-full output..." + @$(SPHINX_BUILD) -M singlemarkdown "$(SOURCE_DIR)" "$(BUILD_DIR)/llm" $(SPHINX_OPTS) $(O) -a \ + -D singlemarkdown_flavor=llm + @# Copy just the files for verification @cp "$(BUILD_DIR)/overrides/markdown/auto-summery.md" "$(BUILD_DIR)/markdown/overrides-auto-summery.md" @cp "$(BUILD_DIR)/overrides/markdown/auto-module.md" "$(BUILD_DIR)/markdown/overrides-auto-module.md" + @cp "$(BUILD_DIR)/singlemarkdown/index.md" "$(BUILD_DIR)/markdown/single.md" + @cp "$(BUILD_DIR)/llm/singlemarkdown/index.md" "$(BUILD_DIR)/markdown/llms-full.txt" @echo "Verifies outputs..." @diff --recursive --color=always --side-by-side --text --suppress-common-lines \ diff --git a/README.md b/README.md index f3814ca..ccfa6d3 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,11 @@ Build markdown files with `sphinx-build` command sphinx-build -M markdown ./docs ./build ``` +Build a single markdown file, containing all your documentation, with: +```sh +sphinx-build -M singlemarkdown ./docs ./build +``` + ## Configurations You can add the following configurations to your `conf.py` file: @@ -38,7 +43,11 @@ You can add the following configurations to your `conf.py` file: * `markdown_uri_doc_suffix`: If set, all references will link to documents with this suffix. * `markdown_file_suffix`: Sets the file extension for generated markdown files (default: `.md`). * `markdown_bullet`: Sets the bullet marker. -* `markdown_flavor`: If set to `github`, output will suit GitHub's flavor of Markdown. +* `markdown_flavor`: + * If set to `github`, output will suit GitHub's flavor of Markdown. + * If set to `llm`, output will be optimized for LLM consumption. +* `singlemarkdown_flavor`: `markdown_flavor` override for the + single-markdown-file builder. For example, if your `conf.py` file have the following configuration: diff --git a/pyproject.toml b/pyproject.toml index 9678e51..82ab8e3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,7 +11,7 @@ description = "A Sphinx extension to add markdown generation support." readme = "README.md" authors = [{ name = "Liran Funaro", email = "liran.funaro@gmail.com" }] license = "MIT" -license-files = ["LICENCE"] +license-files = ["LICENSE"] classifiers = [ "Framework :: Sphinx :: Extension", "Programming Language :: Python", @@ -27,9 +27,11 @@ requires-python = ">=3.7" [tool.poetry.plugins."sphinx.builders"] "markdown" = "sphinx_markdown_builder" +"singlemarkdown" = "sphinx_markdown_builder.singlemarkdown" [project.entry-points."sphinx.builders"] "markdown" = "sphinx_markdown_builder" +"singlemarkdown" = "sphinx_markdown_builder.singlemarkdown" [project.optional-dependencies] dev = [ diff --git a/sphinx_markdown_builder/__init__.py b/sphinx_markdown_builder/__init__.py index 742389f..615e895 100644 --- a/sphinx_markdown_builder/__init__.py +++ b/sphinx_markdown_builder/__init__.py @@ -3,6 +3,7 @@ """ from sphinx_markdown_builder.builder import MarkdownBuilder +from sphinx_markdown_builder.singlemarkdown import SingleFileMarkdownBuilder __version__ = "0.6.10" __docformat__ = "reStructuredText" @@ -10,6 +11,7 @@ def setup(app): app.add_builder(MarkdownBuilder) + app.add_builder(SingleFileMarkdownBuilder) app.add_config_value("markdown_http_base", "", "html", str) app.add_config_value("markdown_uri_doc_suffix", ".md", "html", str) app.add_config_value("markdown_file_suffix", ".md", "html", str) @@ -18,6 +20,7 @@ def setup(app): app.add_config_value("markdown_docinfo", False, "html", bool) app.add_config_value("markdown_bullet", "*", "html", str) app.add_config_value("markdown_flavor", "", "html", str) + app.add_config_value("singlemarkdown_flavor", "", "html", str) return { "version": __version__, diff --git a/sphinx_markdown_builder/builder.py b/sphinx_markdown_builder/builder.py index 1431f44..422c41b 100644 --- a/sphinx_markdown_builder/builder.py +++ b/sphinx_markdown_builder/builder.py @@ -15,6 +15,7 @@ from sphinx.util import logging from sphinx.util.osutil import ensuredir, os_path +from sphinx_markdown_builder.llm import prepare_doctree_for_llm from sphinx_markdown_builder.translator import MarkdownTranslator from sphinx_markdown_builder.writer import MarkdownWriter @@ -89,6 +90,8 @@ def write_doc(self, docname: str, doctree: nodes.document): self.current_doc_name = docname self.sec_numbers = self.env.toc_secnumbers.get(docname, {}) destination = StringOutput(encoding="utf-8") + if self.config.markdown_flavor == "llm": + doctree = prepare_doctree_for_llm(doctree) self.writer.write(doctree, destination) out_filename = os.path.join(self.outdir, f"{os_path(docname)}{self.out_suffix}") ensuredir(os.path.dirname(out_filename)) diff --git a/sphinx_markdown_builder/contexts.py b/sphinx_markdown_builder/contexts.py index fc8951e..a64ee41 100644 --- a/sphinx_markdown_builder/contexts.py +++ b/sphinx_markdown_builder/contexts.py @@ -81,6 +81,7 @@ class ContextStatus: list_marker: Optional[ListMarker] = None # Current list marker desc_type: Optional[str] = None # Current descriptor type default_ref_internal: bool = False # Current default for internal reference + code_language: Optional[str] = None # Default language for subsequent code blocks class SubContext: @@ -215,44 +216,45 @@ def make(self): class TableContext(SubContext): - def __init__(self, params=SubContextParams()): + def __init__(self, params=SubContextParams(), cell_breaker: str = "
"): super().__init__(params) + self.cell_breaker = cell_breaker self.body: List[List[List[str]]] = [] self.headers: List[List[List[str]]] = [] self.internal_context = SubContext() - self.is_entry = False - self.is_header = False - self.is_body = False + # Pack boolean state flags into a single mapping to reduce the + # number of instance attributes (pylint R0902). + self._flags = {"entry": False, "header": False, "body": False} @property def active_output(self) -> List[List[List[str]]]: - if self.is_header: + if self._flags["header"]: return self.headers - assert self.is_body + assert self._flags["body"] return self.body @property def content(self): - if self.is_entry: + if self._flags["entry"]: return self.active_output[-1][-1] return self.internal_context.content def enter_head(self): - assert not self.is_header and not self.is_body - self.is_header = True + assert not self._flags["header"] and not self._flags["body"] + self._flags["header"] = True def exit_head(self): - assert self.is_header and not self.is_body - self.is_header = False + assert self._flags["header"] and not self._flags["body"] + self._flags["header"] = False def enter_body(self): - assert not self.is_header and not self.is_body - self.is_body = True + assert not self._flags["header"] and not self._flags["body"] + self._flags["body"] = True def exit_body(self): - assert self.is_body and not self.is_header - self.is_body = False + assert self._flags["body"] and not self._flags["header"] + self._flags["body"] = False def enter_row(self): self.active_output.append([]) @@ -261,17 +263,16 @@ def exit_row(self): pass def enter_entry(self): - self.is_entry = True + self._flags["entry"] = True self.active_output[-1].append([]) self.ensure_eol_count = 0 def exit_entry(self): - assert self.is_entry - self.is_entry = False + assert self._flags["entry"] + self._flags["entry"] = False - @staticmethod - def make_row(row): - return ["".join(entries).replace("\n", "
") for entries in row] + def make_row(self, row): + return ["".join(entries).replace("\n", getattr(self, "cell_breaker", "
")) for entries in row] def make(self): ctx = SubContext() @@ -327,8 +328,8 @@ def make(self): class TitleContext(NoLineBreakContext): - def __init__(self, level: int, params=SubContextParams(2, 2)): - super().__init__("
", params) + def __init__(self, level: int, params=SubContextParams(2, 2), breaker: str = "
"): + super().__init__(breaker, params) self.level = level @property @@ -377,7 +378,15 @@ def depart_label(self): def make(self): content = super().make() label = self.label_body.make() or self.names - return f"* **[{label}]** {content}" + # https://www.markdownguide.org/extended-syntax/#footnotes + lab = label.strip() + if not lab: + # Fallback to using the raw ids if label is empty + ids = self.ids + if isinstance(ids, (list, tuple)): + ids = ",".join(ids) + lab = str(ids) + return f"[^{lab}]: {content}" _ContextT = TypeVar("_ContextT", bound=SubContext) diff --git a/sphinx_markdown_builder/llm.py b/sphinx_markdown_builder/llm.py new file mode 100644 index 0000000..8fdee61 --- /dev/null +++ b/sphinx_markdown_builder/llm.py @@ -0,0 +1,56 @@ +"""Helpers to prune and normalize a docutils doctree for LLM-friendly output.""" + +from __future__ import annotations + +from typing import cast + +from docutils import nodes + +_NAV_ARTIFACT_TEXTS = frozenset({"genindex", "modindex", "search"}) + + +def _remove_node(node: nodes.Node) -> None: + if node.parent is not None: + node.parent.remove(node) + + +def _is_nav_artifact_list_item(node: nodes.list_item) -> bool: + text = " ".join(node.astext().split()).strip().lower() + return text in _NAV_ARTIFACT_TEXTS + + +def _remove_nav_artifact_lists(doc: nodes.document) -> None: + for bullet_list in list(doc.findall(nodes.bullet_list)): + list_items = [child for child in bullet_list.children if isinstance(child, nodes.list_item)] + if list_items and all(_is_nav_artifact_list_item(item) for item in list_items): + _remove_node(bullet_list) + + +def _prune_empty_containers(doc: nodes.document) -> None: + changed = True + while changed: + changed = False + + for bullet_list in list(doc.findall(nodes.bullet_list)): + if len(bullet_list.children) == 0: + _remove_node(bullet_list) + changed = True + + for section in list(doc.findall(nodes.section)): + children_without_title = [child for child in section.children if not isinstance(child, nodes.title)] + if len(children_without_title) == 0: + _remove_node(section) + changed = True + + +def prepare_doctree_for_llm(doc: nodes.document) -> nodes.document: + llm_doc = cast(nodes.document, doc.deepcopy()) + for target in list(llm_doc.findall(nodes.target)): + _remove_node(target) + for transition in list(llm_doc.findall(nodes.transition)): + _remove_node(transition) + for comment in list(llm_doc.findall(nodes.comment)): + _remove_node(comment) + _remove_nav_artifact_lists(llm_doc) + _prune_empty_containers(llm_doc) + return llm_doc diff --git a/sphinx_markdown_builder/singlemarkdown.py b/sphinx_markdown_builder/singlemarkdown.py new file mode 100644 index 0000000..783e488 --- /dev/null +++ b/sphinx_markdown_builder/singlemarkdown.py @@ -0,0 +1,273 @@ +"""Single Markdown builder.""" + +# pyright: reportIncompatibleMethodOverride=false, reportImplicitOverride=false + +from __future__ import annotations + +import os +import re +from typing import TYPE_CHECKING, Optional, Sequence, Union, cast + +from docutils import nodes +from docutils.io import StringOutput +from sphinx._cli.util.colour import darkgreen +from sphinx.environment.adapters.toctree import global_toctree_for_doc +from sphinx.locale import __ +from sphinx.util import logging +from sphinx.util.docutils import SphinxTranslator, new_document +from sphinx.util.nodes import inline_all_toctrees +from sphinx.util.osutil import ensuredir, os_path + +from sphinx_markdown_builder.builder import MarkdownBuilder +from sphinx_markdown_builder.llm import prepare_doctree_for_llm +from sphinx_markdown_builder.translator import MarkdownTranslator +from sphinx_markdown_builder.writer import MarkdownWriter + +if TYPE_CHECKING: + from sphinx.application import Sphinx + from sphinx.util.typing import ExtensionMetadata + +logger = logging.getLogger(__name__) + + +class SingleFileMarkdownBuilder(MarkdownBuilder): + """Builds the whole document tree as a single Markdown page.""" + + name: str = "singlemarkdown" + epilog: str = __("The Markdown page is in %(outdir)s.") + + # These are copied from SingleFileHTMLBuilder + copysource: bool = False + + default_translator_class: type[SphinxTranslator] = MarkdownTranslator + heading_level_offset: int = 0 + + def _cleanup_for_llm(self, content: str) -> str: + # Normalize whitespace while keeping paragraph breaks intact. + content = re.sub(r"[ \t]+\n", "\n", content) + content = re.sub(r"\n{3,}", "\n\n", content) + return content.strip() + "\n" + + def _render_doctree(self, doctree: nodes.document) -> str: + writer = MarkdownWriter(self) + destination = StringOutput(encoding="utf-8") + _ = writer.write(doctree, destination) + return writer.output or "" + + def _render_toctree_fragment(self, docname: str, collapse: bool = False) -> str: + toctree = global_toctree_for_doc(self.env, docname, self, collapse=collapse) + return str(self.render_partial(toctree)["fragment"]) if toctree else "" + + def _ordered_docnames(self, root_doc: str) -> list[str]: + """Return documents in depth-first toctree order from the root document.""" + docnames: list[str] = [] + seen: set[str] = set() + raw_toctree_includes = getattr(self.env, "toctree_includes", None) + toctree_includes = raw_toctree_includes if isinstance(raw_toctree_includes, dict) else {} + + def visit(docname: str) -> None: + if docname in seen: + return + seen.add(docname) + docnames.append(docname) + for child in toctree_includes.get(docname, []): + visit(child) + + visit(root_doc) + return docnames + + def get_outdated_docs(self) -> Union[str, list[str]]: + return "all documents" + + def get_target_uri(self, docname: str, typ: Optional[str] = None) -> str: + if docname in self.env.all_docs: + return f"#{docname}" + return docname + self.out_suffix + + def get_relative_uri(self, from_: str, to: str, typ: Optional[str] = None) -> str: + return self.get_target_uri(to, typ) + + def render_partial(self, node: Optional[nodes.Node]) -> dict[str, Union[str, bytes]]: + """Utility: Render a lone doctree node.""" + if node is None: + return {"fragment": ""} + doctree = node if isinstance(node, nodes.document) else new_document("", self.env.settings) + if doctree is not node: + doctree.append(node) + fragment = self._render_doctree(doctree) + return { + "fragment": fragment, + "title": "", + "css": "", + "js": "", + "script": "", + } + + def _get_local_toctree( + self, + docname: str, + collapse: bool = True, + **kwargs: Union[bool, int, str], + ) -> str: + includehidden = kwargs.get("includehidden") + if isinstance(includehidden, str): + if includehidden.lower() == "false": + kwargs["includehidden"] = False + elif includehidden.lower() == "true": + kwargs["includehidden"] = True + if kwargs.get("maxdepth") == "": + _ = kwargs.pop("maxdepth") + toctree = global_toctree_for_doc( + self.env, + docname, + self, + collapse=collapse, + **kwargs, # pyright: ignore[reportArgumentType] + ) + return str(self.render_partial(toctree)["fragment"]) + + def assemble_doctree(self) -> nodes.document: + master = cast(str, self.config.root_doc) + tree = self.env.get_doctree(master) + tree = inline_all_toctrees(self, set(), master, tree, darkgreen, [master]) + tree["docname"] = master + self.env.resolve_references(tree, master, self) + return tree + + def assemble_toc_secnumbers(self) -> dict[str, dict[str, tuple[int, ...]]]: + new_secnumbers: dict[str, tuple[int, ...]] = {} + for docname, secnums in self.env.toc_secnumbers.items(): + for id_, secnum in secnums.items(): + alias = f"{docname}/{id_}" + new_secnumbers[alias] = secnum + + root_doc = cast(str, self.config.root_doc) + return {root_doc: new_secnumbers} + + def assemble_toc_fignumbers( + self, + ) -> dict[str, dict[str, dict[str, tuple[int, ...]]]]: + new_fignumbers: dict[str, dict[str, tuple[int, ...]]] = {} + for docname, fignumlist in self.env.toc_fignumbers.items(): + for figtype, fignums in fignumlist.items(): + alias = f"{docname}/{figtype}" + _ = new_fignumbers.setdefault(alias, {}) + for id_, fignum in fignums.items(): + new_fignumbers[alias][id_] = fignum + + root_doc = cast(str, self.config.root_doc) + return {root_doc: new_fignumbers} + + def get_doc_context( + self, + docname: str, # pylint: disable=unused-argument # pyright: ignore[reportUnusedParameter] + body: str, + metatags: str, + ) -> dict[str, Union[str, bytes, bool, list[dict[str, str]], None]]: + root_doc = cast(str, self.config.root_doc) + toc = self._render_toctree_fragment(root_doc, collapse=False) + return { + "parents": [], + "prev": None, + "next": None, + "docstitle": None, + "title": cast(str, self.config.html_title), + "meta": None, + "body": body, + "metatags": metatags, + "rellinks": [], + "sourcename": "", + "toc": toc, + "display_toc": bool(toc), + } + + def _append_table_of_contents(self, content_parts: list[str], docnames: list[str], root_doc: str) -> None: + content_parts.append("## Table of Contents\n\n") + for docname in docnames: + if docname == root_doc: + content_parts.append(f"* [Main Document](#{docname})\n") + continue + title = docname.rsplit("/", 1)[-1].replace("_", " ").replace("-", " ").title() + content_parts.append(f"* [{title}](#{docname})\n") + content_parts.append("\n") + + def _append_doc_content(self, content_parts: list[str], docname: str, llm_cleanup_enabled: bool) -> None: + logger.info("Adding content from %s", docname) + previous_doc_name = self.current_doc_name + self.current_doc_name = docname + try: + doc = self.env.get_doctree(docname) + if llm_cleanup_enabled: + doc = prepare_doctree_for_llm(doc) + else: + content_parts.append(f'\n\n\n') + content_parts.append(self._render_doctree(doc)) + content_parts.append("\n\n") + except Exception as e: # pylint: disable=broad-exception-caught + logger.warning("Error adding content from %s: %s", docname, e) + finally: + self.current_doc_name = previous_doc_name + + def _write_single_markdown(self) -> None: + project = cast(str, self.config.project) + root_doc = cast(str, self.config.root_doc) + docnames = self._ordered_docnames(root_doc) + flavor = self.config.singlemarkdown_flavor or self.config.markdown_flavor + content_parts: list[str] = [f"# {project} Documentation\n\n"] + + had_offset_attr = hasattr(self, "heading_level_offset") + previous_offset = cast(int, getattr(self, "heading_level_offset", 0)) + # Keep the synthetic documentation title as the only H1. + self.heading_level_offset = 1 + + try: + if flavor != "llm": + self._append_table_of_contents(content_parts, docnames, root_doc) + for docname in docnames: + self._append_doc_content(content_parts, docname, flavor == "llm") + finally: + if had_offset_attr: + self.heading_level_offset = previous_offset + else: + delattr(self, "heading_level_offset") + + final_content = "".join(content_parts) + if flavor == "llm": + final_content = self._cleanup_for_llm(final_content) + outfilename = os.path.join(self.outdir, os_path(root_doc) + self.out_suffix) + ensuredir(os.path.dirname(outfilename)) + + try: + with open(outfilename, "w", encoding="utf-8") as f: + _ = f.write(final_content) + except OSError as err: + logger.warning(__("error writing file %s: %s"), outfilename, err) + + # Sphinx >=8 uses write_documents() as the extension hook. + def write_documents(self, _docnames: set[str]) -> None: + self._write_single_markdown() + + # Sphinx <=7 does not expose write_documents(), so route the legacy hooks + # to the same single-file generation path. + def _write_serial(self, _docnames: Sequence[str]) -> None: + self._write_single_markdown() + + def _write_parallel(self, _docnames: Sequence[str], _nproc: int) -> None: + self._write_single_markdown() + + +def setup(app: Sphinx) -> ExtensionMetadata: + """Setup the singlemarkdown builder extension. + + This follows the pattern from Sphinx's own singlehtml.py. + """ + # Setup the main extension first + app.setup_extension("sphinx_markdown_builder") + + # No need to register the builder here as it's already registered in __init__.py + + return { + "version": "builtin", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/sphinx_markdown_builder/translator.py b/sphinx_markdown_builder/translator.py index 127fc5e..56477df 100644 --- a/sphinx_markdown_builder/translator.py +++ b/sphinx_markdown_builder/translator.py @@ -61,7 +61,7 @@ DOC_INFO_FIELDS = "author", "contact", "copyright", "date", "organization", "revision", "status", "version" # Defines context items, skip, or None (keep processing sub-tree). -PREDEFINED_ELEMENTS: Dict[str, Union[PushContext, SKIP, None]] = dict( # pylint: disable=use-dict-literal +PREDEFINED_ELEMENTS: Dict[str, Union[PushContext, UniqueString, None]] = dict( # pylint: disable=use-dict-literal # Doctree elements for which Markdown element is emphasis=ITALIC_CONTEXT, strong=STRONG_CONTEXT, @@ -85,10 +85,13 @@ index=SKIP, substitution_definition=SKIP, # the doctree already contains the text with substitutions applied. runrole_reference=SKIP, + toctree=SKIP, + viewcode_anchor=SKIP, # Doctree elements to ignore document=None, container=None, inline=None, + abbreviation=None, definition_list=None, definition_list_item=None, glossary=None, @@ -108,6 +111,7 @@ colspec=None, tgroup=None, figure=None, + caption=None, desc_signature_line=None, ) @@ -163,6 +167,20 @@ def ctx(self) -> SubContext: def _push_context(self, ctx: SubContext): self._ctx_queue.append(ctx) + def _title_level(self, base_level: int) -> int: + offset = int(getattr(self.builder, "heading_level_offset", 0)) + return min(6, max(1, base_level + offset)) + + def _title_breaker(self) -> str: + if self.config.markdown_flavor == "llm": + return " " + return "
" + + def _table_cell_breaker(self) -> str: + if self.config.markdown_flavor == "llm": + return " " + return "
" + def _pop_context(self, _node=None, count=1): for _ in range(count): if len(self._ctx_queue) <= 1: @@ -173,9 +191,15 @@ def _pop_context(self, _node=None, count=1): ctx.add(last_ctx.make(), last_ctx.params.prefix_eol, last_ctx.params.suffix_eol) def _push_box(self, title: str): - self.add(f"#### {title}", prefix_eol=2) + level = self._title_level(4) + self.add(f"{'#' * level} {title}", prefix_eol=2) self._push_context(SubContext(SubContextParams(1, 2))) + def _push_admonition(self, title: str): + level = self._title_level(5) + self._push_context(IndentContext("> ", empty=True, params=SubContextParams(1, 2))) + self.add(f"{'#' * level} {title}", prefix_eol=1, suffix_eol=1) + @property def status(self) -> ContextStatus: return self._status_queue[-1] @@ -308,31 +332,39 @@ def unknown_visit(self, node): @pushing_context def visit_important(self, _node): """Sphinx important directive.""" - self._push_box("IMPORTANT") + self._push_admonition("IMPORTANT") @pushing_context def visit_warning(self, _node): """Sphinx warning directive.""" - self._push_box("WARNING") + self._push_admonition("WARNING") + + @pushing_context + def visit_caution(self, _node): + self._push_admonition("CAUTION") @pushing_context def visit_note(self, _node): """Sphinx note directive.""" - self._push_box("NOTE") + self._push_admonition("NOTE") @pushing_context def visit_seealso(self, _node): """Sphinx see also directive.""" - self._push_box("SEE ALSO") + self._push_admonition("SEE ALSO") @pushing_context def visit_attention(self, _node): - self._push_box("ATTENTION") + self._push_admonition("ATTENTION") @pushing_context def visit_hint(self, _node): """Sphinx hint directive.""" - self._push_box("HINT") + self._push_admonition("HINT") + + @pushing_context + def visit_tip(self, _node): + self._push_admonition("TIP") def visit_image(self, node): """Image directive.""" @@ -389,6 +421,8 @@ def visit_line(self, _node): def depart_line(self, _node): self._pop_context() + if self.config.markdown_flavor == "llm": + return self.add("
", prefix_eol=1, suffix_eol=1) ################################################################################ @@ -447,9 +481,18 @@ def depart_literal(self, _node): def visit_literal_block(self, node): self._push_status(escape_text=False) - code_type = node["classes"][1] if "code" in node["classes"] else "" + code_type = "" + classes = node.get("classes", []) + if "code" in classes: + code_idx = classes.index("code") + 1 + if code_idx < len(classes): + code_type = classes[code_idx] if "language" in node: code_type = node["language"] + elif self.status.code_language: + code_type = self.status.code_language + if code_type == "default": + code_type = "" self.add(f"```{code_type}", prefix_eol=1, suffix_eol=1) def depart_literal_block(self, _node): @@ -485,7 +528,7 @@ def visit_title(self, _node): level = 4 else: level = self.status.section_level - self._push_context(TitleContext(level)) + self._push_context(TitleContext(self._title_level(level), breaker=self._title_breaker())) @pushing_context @pushing_status @@ -495,12 +538,12 @@ def visit_subtitle(self, _node): # pragma: no cover However, we keep it here in case some future version will change this behaviour. """ self._push_status(section_level=self.status.section_level + 1) - self._push_context(TitleContext(self.status.section_level)) + self._push_context(TitleContext(self._title_level(self.status.section_level), breaker=self._title_breaker())) @pushing_context def visit_rubric(self, _node): """Sphinx Rubric, a heading without relation to the document sectioning""" - self._push_context(TitleContext(3)) + self._push_context(TitleContext(self._title_level(3), breaker=self._title_breaker())) def visit_transition(self, _node): """Simply replace a transition by a horizontal rule.""" @@ -508,6 +551,14 @@ def visit_transition(self, _node): self.add("---", prefix_eol=2, suffix_eol=1) raise nodes.SkipNode + def visit_only(self, node): + expr = node.get("expr", "") + tags = getattr(self.builder, "tags", None) + if not expr or tags is None: + return + if not tags.eval_condition(expr): + raise nodes.SkipNode + def _adjust_url(self, url: str): """Replace `refuri` in reference with HTTP address, if possible""" if not self.config.markdown_http_base: @@ -541,15 +592,34 @@ def _fetch_ref_uri(self, node): @pushing_context def visit_reference(self, node): + # If this reference was already moved into a card title, skip it. + if node.get("md_moved_to_title", False): + raise nodes.SkipNode + + is_internal = bool(node.get("internal", self.status.default_ref_internal)) + is_llm = self.config.markdown_flavor == "llm" + is_single = getattr(self.builder, "name", "") == "singlemarkdown" + if is_llm and is_single and is_internal: + self._push_context(WrappedContext("", "")) + return + url = self._fetch_ref_uri(node) self._push_context(WrappedContext("[", f"]({url})")) + def visit_pending_xref(self, node): + # Keep default behavior (child text passes through), unless this node + # was already moved into a card title link. + if node.get("md_moved_to_title", False): + raise nodes.SkipNode + @pushing_context def visit_download_reference(self, node): reftarget = self._adjust_url(node.get("reftarget", "")) self._push_context(WrappedContext("[", f"]({reftarget})")) def _add_anchor(self, anchor: str): + if self.config.markdown_flavor == "llm": + return content = f'' # Prevent adding the same anchor twice in the same context if content not in self.ctx.content: @@ -567,6 +637,108 @@ def visit_topic(self, _node): self._push_status(default_ref_internal=True, section_level=5) self._push_context(IndentContext("> ", empty=True)) + def visit_container(self, node): + """Handle generic container nodes and special-case sphinx-design cards. + + We push a blockquote context for top-level sphinx-design cards (class + `sd-card`) so their contents are rendered as a Markdown blockquote. We + also special-case containers with class `sd-card-title` to render the + title as a linked level-4 heading inside the blockquote. + """ + classes = node.attributes.get("classes", []) or [] + + # Handle sphinx-design card containers and titles using small helpers + # to keep this method simple and under the complexity threshold. + if "sd-card" in classes: + self._handle_sd_card(node) + return + + if "sd-card-title" in classes: + self._handle_sd_card_title(node) + return + + def _handle_sd_card(self, node): + # Ensure an extra blank line after the card so adjacent cards don't + # merge into the same blockquote in Markdown output. + self._push_context(IndentContext("> ", empty=True, params=SubContextParams(1, 2))) + # mark the node so depart_container knows to pop + # Store a marker in the node attributes when possible so downstream + # handlers can detect that we pushed a card context. Use the node + # attribute mapping if available to avoid touching protected members. + if hasattr(node, "attributes") and isinstance(node.attributes, dict): + node["md_card_pushed"] = True + + def _find_card_container(self, node): + container = node + while container is not None and "sd-card" not in (container.attributes.get("classes", []) or []): + container = getattr(container, "parent", None) + return container + + def _find_stretched_link(self, container): + if container is None: + return None + for child in container.traverse(): + child_classes = child.attributes.get("classes", []) if hasattr(child, "attributes") else [] + if "sd-stretched-link" in child_classes: + return child + return None + + def _href_from_link_node(self, link_node): + if link_node is None: + return None + if isinstance(link_node, nodes.reference): + try: + return self._fetch_ref_uri(link_node) + except (AttributeError, KeyError, TypeError): + return "" + return link_node.get("refuri") or link_node.get("reftarget") or "" + + def _normalize_card_href(self, href: Optional[str]) -> Optional[str]: + if not href: + return href + if href.endswith(".html"): + return href[:-5] + (self.config.markdown_uri_doc_suffix or ".md") + is_http = href.startswith("http://") or href.startswith("https://") + if not (is_http or href.endswith(self.config.markdown_uri_doc_suffix)): + return href + (self.config.markdown_uri_doc_suffix or ".md") + return href + + def _handle_sd_card_title(self, node): + container = self._find_card_container(node) + link_node = self._find_stretched_link(container) + + title = node.astext().strip() + level = self._title_level(4) + + href = self._href_from_link_node(link_node) + if link_node is not None: + if hasattr(link_node, "attributes") and isinstance(link_node.attributes, dict): + link_node["md_moved_to_title"] = True + + href = self._normalize_card_href(href) + + if self.status.escape_text: + title = escape_markdown_chars(title) + + is_llm = self.config.markdown_flavor == "llm" + is_singlemarkdown = getattr(self.builder, "name", "") == "singlemarkdown" + is_internal_href = href and not (href.startswith("http://") or href.startswith("https://")) + + if is_llm and is_singlemarkdown and is_internal_href: + self.add(f"{('#' * level)} {title}", prefix_eol=1, suffix_eol=1) + elif href: + self.add(f"{('#' * level)} [{title}]({href})", prefix_eol=1, suffix_eol=1) + else: + self.add(f"{('#' * level)} {title}", prefix_eol=1, suffix_eol=1) + + raise nodes.SkipNode + + def depart_container(self, node): + # If we marked the node as having pushed a card context, pop it now. + if node.get("md_card_pushed", False): + if len(self._ctx_queue) > 1: + self._pop_context(node) + ################################################################################ # lists ################################################################################ @@ -641,7 +813,7 @@ def visit_desc_signature(self, node): # If signature has a non-null class, that's means it is a signature # of a class method h_level = 4 if node.get("class", None) else 3 - self._push_context(TitleContext(h_level)) + self._push_context(TitleContext(self._title_level(h_level))) def visit_desc_parameterlist(self, _node): self._push_context(WrappedContext("(", ")", wrap_empty=True)) @@ -651,17 +823,26 @@ def depart_desc_parameterlist(self, _node): self._pop_context(count=2) @property - def sep_ctx(self) -> CommaSeparatedContext: - ctx = self.ctx - assert isinstance(ctx, CommaSeparatedContext) - return ctx + def sep_ctx(self) -> Optional[CommaSeparatedContext]: + for ctx in reversed(self._ctx_queue): + if isinstance(ctx, CommaSeparatedContext): + return ctx + return None def visit_desc_parameter(self, _node): """single method/class ctr param""" - self.sep_ctx.enter_parameter() # workaround pylint: disable=no-member + sep_ctx = self.sep_ctx + if sep_ctx is not None: + sep_ctx.enter_parameter() # workaround pylint: disable=no-member def depart_desc_parameter(self, _node): - self.sep_ctx.exit_parameter() # workaround pylint: disable=no-member + sep_ctx = self.sep_ctx + if sep_ctx is not None: + sep_ctx.exit_parameter() # workaround pylint: disable=no-member + + @pushing_context + def visit_desc_optional(self, _node): + self._push_context(WrappedContext("[", "]")) def visit_field_list(self, _node): self._start_list("*") @@ -687,6 +868,11 @@ def visit_versionmodified(self, node): node_type = node.attributes["type"].capitalize() self._push_box(node_type) + def visit_highlightlang(self, node): + """Apply default language for subsequent literal blocks.""" + lang = node.get("lang", "") + self._status_queue[-1] = dataclasses.replace(self.status, code_language=lang) + ################################################################################ # tables ################################################################################ @@ -711,7 +897,7 @@ def table_ctx(self) -> TableContext: @pushing_context def visit_table(self, _node): - self._push_context(TableContext(params=SubContextParams(2, 1))) + self._push_context(TableContext(params=SubContextParams(2, 1), cell_breaker=self._table_cell_breaker())) def visit_thead(self, _node): self.table_ctx.enter_head() # workaround pylint: disable=no-member @@ -754,9 +940,9 @@ def footnote_ctx(self) -> FootNoteContext: return ctx @pushing_context - def visit_footnote_reference(self, node): - ref_id = node.get("refid", "") - self._push_context(WrappedContext("[", f"](#{ref_id})")) + def visit_footnote_reference(self, _node): + # https://www.markdownguide.org/extended-syntax/#footnotes + self._push_context(WrappedContext("[^", "]")) @pushing_context def visit_footnote(self, node): @@ -766,6 +952,7 @@ def visit_footnote(self, node): names = node.get("names", "") if isinstance(names, (list, tuple)): names = ",".join(names) + # https://www.markdownguide.org/extended-syntax/#footnotes self._push_context(FootNoteContext(ids, names, params=SubContextParams(1, 1))) def visit_label(self, node): diff --git a/tests/expected/ExampleRSTFile.md b/tests/expected/ExampleRSTFile.md index d711808..dec84df 100644 --- a/tests/expected/ExampleRSTFile.md +++ b/tests/expected/ExampleRSTFile.md @@ -43,21 +43,25 @@ This is an example of regular text in paragraph form. There are no indents. As a best practice, break lines at about 80 characters, so that each line has its own line number for commenting in reviews. -#### WARNING -Throughout text and code examples, make sure double quotation -marks and apostrophes are straight (”) or (‘), not curly quotatation marks -and apostrophes, which might be introduced when text is cut and pasted from -other sources or editors. +> ##### WARNING +> +> Throughout text and code examples, make sure double quotation +> marks and apostrophes are straight (”) or (‘), not curly quotatation marks +> and apostrophes, which might be introduced when text is cut and pasted from +> other sources or editors. -#### ATTENTION -Boldface is used for labels that are visible in the user interface. The UI -text is surrounded by double asterisks. For example, **bold**. +> ##### ATTENTION +> +> Boldface is used for labels that are visible in the user interface. The UI +> text is surrounded by double asterisks. For example, **bold**. -#### IMPORTANT -This is an important message. +> ##### IMPORTANT +> +> This is an important message. -#### HINT -This is a hint message. +> ##### HINT +> +> This is a hint message. Italics are rarely used. Text surrounded by single asterisks is rendered in *italics*. @@ -81,9 +85,10 @@ Use hash symbols for ordered lists. 2. Find the **Course Advertised Start Date** policy key. 3. Enter the value you want to display. -#### NOTE -Ordered lists usually use numerals. Nested ordered lists (ordered lists inside -other ordered lists) use letters. +> ##### NOTE +> +> Ordered lists usually use numerals. Nested ordered lists (ordered lists inside +> other ordered lists) use letters. Use asterisks for unordered (bulleted) lists. @@ -206,7 +211,7 @@ indented under the only directive. ## Notes and Warnings -```default +``` .. note:: This is note text. If note text runs over a line, make sure the lines wrap and are indented to the same level as the note tag. If formatting is @@ -216,23 +221,25 @@ indented under the only directive. to the same level as the rest of the note. ``` -#### NOTE -This is note text. If note text runs over a line, make sure the lines wrap -and are indented to the same level as the note tag. If formatting is -incorrect, part of the note might not render in the HTML output. - -Notes can have more than one paragraph. Successive paragraphs must indent to -the same level as the rest of the note. +> ##### NOTE +> +> This is note text. If note text runs over a line, make sure the lines wrap +> and are indented to the same level as the note tag. If formatting is +> incorrect, part of the note might not render in the HTML output. +> +> Notes can have more than one paragraph. Successive paragraphs must indent to +> the same level as the rest of the note. -```default +``` .. warning:: Warnings are formatted in the same way as notes. In the same way, lines must be broken and indented under the warning tag. ``` -#### WARNING -Warnings are formatted in the same way as notes. In the same way, lines must -be broken and indented under the warning tag. +> ##### WARNING +> +> Warnings are formatted in the same way as notes. In the same way, lines must +> be broken and indented under the warning tag. ## Cross-References @@ -253,7 +260,7 @@ above the heading for each topic or section. Anchors can contain numbers, letters, spaces, underscores, and hyphens, but cannot include punctuation. Anchors use the following syntax. -```default +``` .. _Anchor Text: ``` @@ -281,7 +288,7 @@ In this example, “SFD SN Keyboard Shortcuts” is the anchor text for a sectio that is titled “Keyboard Shortcuts for Notes”. Readers will see the following text, and “Keyboard Shortcuts for Notes” will be an active link. -```default +``` For more information about using keyboard shortcuts, see Keyboard Shortcuts for Notes. ``` @@ -294,16 +301,17 @@ syntax, as in the following example. If you want to, you can use [keyboard shortcuts](#sfd-sn-keyboard-shortcuts) to create, edit, and view notes. -#### NOTE -Do not include a space between the last word of the link text and the opening -angle bracket for the anchor text. +> ##### NOTE +> +> Do not include a space between the last word of the link text and the opening +> angle bracket for the anchor text. In this example, “keyboard shortcuts” is the link text, and “SFD SN Keyboard Shortcuts” is the anchor text for a section that is titled “Keyboard Shortcuts for Notes”. Readers will see the following text, and “keyboard shortcuts” will be an active link. -```default +``` If you want to, you can use keyboard shortcuts to create, edit, and view your notes. ``` @@ -316,7 +324,7 @@ you can create a link in *Building and Running an edX Course* to a topic in the document that you want to link to and the anchor text for the section you want. The cross-reference uses the following syntax. -```default +``` :ref:`intersphinx_map_ID:Anchor Name` ``` @@ -369,7 +377,7 @@ To create an external cross-reference, follow these steps. 1. In the paragraph where you want the cross-reference, add the text that you want to use for the link, formatted as follows (where “Release Pages” is the link text). This creates an anchor out of that text. - ```default + ``` The edX engineering wiki `Release Pages`_ provide access to detailed information about every change made to the edx-platform GitHub repository. @@ -378,25 +386,26 @@ To create an external cross-reference, follow these steps. for the `edx-documentation/en_us/links/links.rst` file if one does not already exist. These `include` directives are typically at the end of the file. - ```default + ``` .. include:: ../../links/links.rst ``` - #### NOTE - The path to the links.rst file depends on the location of the file where - you are creating the link. For example, the path might be - `../../../links/links.rst` or `../links/links.rst`. + > ##### NOTE + > + > The path to the links.rst file depends on the location of the file where + > you are creating the link. For example, the path might be + > `../../../links/links.rst` or `../links/links.rst`. 3. In the `edx-documentation/en_us/links/links.rst` file, add an entry for the anchor text and the URL of the external website, formatted as follows. Make sure that the anchor text in this file matches the anchor text in the file that contains the cross-reference exactly, including capitalization. - ```default + ``` .. _Release Pages: https://openedx.atlassian.net/wiki/display/ENG/Release+Pages ``` Readers will see the following text. “Release Pages” will be an active link. -```default +``` The edX engineering wiki Release Pages provide access to detailed information about every change made to the edx-platform GitHub repository. @@ -428,7 +437,7 @@ Style Guide). The empty cell is the second column in the first row of this table. -```default +``` .. list-table:: :widths: 25 25 50 @@ -459,7 +468,7 @@ The empty cell is the second column in the first row of this table. ### Example of a table with a header row -```default +``` .. list-table:: :widths: 15 15 70 :header-rows: 1 @@ -482,7 +491,7 @@ The empty cell is the second column in the first row of this table. ### Example of a table with a boldface first column -```default +``` .. list-table:: :widths: 15 15 70 :stub-columns: 1 @@ -508,7 +517,7 @@ The empty cell is the second column in the first row of this table. The blank lines before and after the unordered list are critical for the list to render correctly. -```default +``` .. list-table:: :widths: 15 15 60 :header-rows: 1 @@ -558,7 +567,7 @@ To set text in a code block, end the previous paragaph with 2 colons, leave one line before the intended code block, and make sure the code block is indented beyond the first colon. -```default +``` For example, this is the introductory paragraph :: diff --git a/tests/expected/auto-module.md b/tests/expected/auto-module.md index a78e3f9..e19fc13 100644 --- a/tests/expected/auto-module.md +++ b/tests/expected/auto-module.md @@ -58,10 +58,10 @@ This is a function with two parameters. This is a function with two parameters. * **Parameters:** - * **param1** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Alice [1](#id3). - * **param2** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Bon [2](#id4). + * **param1** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Alice [^1]. + * **param2** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Bon [^2]. ## References -* **[1]** Alice is commonly used to describe the first actor. -* **[2]** Bob is commonly used to describe the second actor. +[^1]: Alice is commonly used to describe the first actor. +[^2]: Bob is commonly used to describe the second actor. diff --git a/tests/expected/library/my_module.md b/tests/expected/library/my_module.md index ca0ceb5..bb3e9d4 100644 --- a/tests/expected/library/my_module.md +++ b/tests/expected/library/my_module.md @@ -66,10 +66,10 @@ This is a function with two parameters. This is a function with two parameters. * **Parameters:** - * **param1** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Alice [1](#id3). - * **param2** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Bon [2](#id4). + * **param1** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Alice [^1]. + * **param2** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Bon [^2]. ## References -* **[1]** Alice is commonly used to describe the first actor. -* **[2]** Bob is commonly used to describe the second actor. +[^1]: Alice is commonly used to describe the first actor. +[^2]: Bob is commonly used to describe the second actor. diff --git a/tests/expected/library/my_module.module_class.md b/tests/expected/library/my_module.module_class.md index c16fba4..d67ca33 100644 --- a/tests/expected/library/my_module.module_class.md +++ b/tests/expected/library/my_module.module_class.md @@ -28,5 +28,6 @@ This is a dummy function that does not do anything. * **Return type:** None -#### SEE ALSO -[`function()`](my_module.submodule.my_class.md#my_module.submodule.my_class.SubmoduleClass.function) +> ##### SEE ALSO +> +> [`function()`](my_module.submodule.my_class.md#my_module.submodule.my_class.SubmoduleClass.function) diff --git a/tests/expected/llms-full.txt b/tests/expected/llms-full.txt new file mode 100644 index 0000000..4e27ff0 --- /dev/null +++ b/tests/expected/llms-full.txt @@ -0,0 +1,970 @@ +# sphinx_markdown_builder Documentation + +## Main Test File + +## Example .rst File + +If you work with edX documentation source files, you might find this file +helpful as a reference. This file contains examples of .rst formatting. + +Explanations and more context for each type of element are provided in +“Work with edX Documentation Source Files”. + +This file covers the following topics. + +> ###### Table of content +> +> * [Heading Levels](#heading-levels) +> * [Paragraph Text and Commented Text](#paragraph-text-and-commented-text) +> * [Ordered and Unordered Lists](#ordered-and-unordered-lists) +> * [Conditional Text](#conditional-text) +> * [Notes and Warnings](#notes-and-warnings) +> * [Cross-References](#cross-references) +> * [Image References](#image-references) +> * [Tables](#tables) +> * [Code Formatting](#code-formatting) +> * [Links](#links) + +### Heading Levels + +The top of the document is heading 1, and this section is heading 2. The following are the rest of the headers. + +### Paragraph Text and Commented Text + +This is an example of regular text in paragraph form. There are no indents. As +a best practice, break lines at about 80 characters, so that each line has its +own line number for commenting in reviews. + +> ###### WARNING +> +> Throughout text and code examples, make sure double quotation +> marks and apostrophes are straight (”) or (‘), not curly quotatation marks +> and apostrophes, which might be introduced when text is cut and pasted from +> other sources or editors. + +> ###### ATTENTION +> +> Boldface is used for labels that are visible in the user interface. The UI +> text is surrounded by double asterisks. For example, **bold**. + +> ###### IMPORTANT +> +> This is an important message. + +> ###### HINT +> +> This is a hint message. + +Italics are rarely used. Text surrounded by single asterisks is rendered in +*italics*. + +Monospace text is used for `code examples`. Text surrounded by double grave +accent characters is rendered in monospace font. + +In English source files, look for comments addressed to translators from writers. + +`.. Translators: In this code example, do not translate such and such.` + +### Ordered and Unordered Lists + +Use hash symbols for ordered lists. + +1. Select **Advanced Settings**. +2. Find the **Course Advertised Start Date** policy key. +3. Enter the value you want to display. + +> ###### NOTE +> +> Ordered lists usually use numerals. Nested ordered lists (ordered lists inside +> other ordered lists) use letters. + +Use asterisks for unordered (bulleted) lists. + +* Who is teaching the course? +* What university or college is the course affiliated with? +* What topics and concepts are covered in your course? +* Why should a learner enroll in your course? + +#### Nested Lists or Content + +You can include content including additional lists and code examples inside +lists. + +##### Unordered List inside Ordered List + +To include an unordered list inside an ordered list, indent the unordered list +three spaces. The first bullet in the unordered list must be flush with the +text in the ordered list. + +1. Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be + comma separated. + * In this example, the key for the Annotation Problem tool is the only + value in the list. + * In this example, the key for the Annotation Problem tool is added at + the beginning of a list of other keys. +2. Select **Save Changes**. + +![An unordered (bulleted) list inside an ordered (numbered) list.](static/markdown.png) + +##### Ordered List inside Unordered List + +To include an ordered list inside an unordered list, indent the ordered list +two spaces. The first number or letter of the ordered list must be flush with +the text in the unordered list. + +* Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be comma + separated. + 1. In this example, the key for the Annotation Problem tool is the only + value in the list. + 2. In this example, the key for the Annotation Problem tool is added at the + beginning of a list of other keys. +* Select **Save Changes**. + +##### Unordered List inside Unordered List + +To include an unordered list inside another unordered list, indent the second +unordered list two spaces. The first bullet of the second unordered list must +be flush with the text in the unordered list. + +* Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be + comma separated. + 1. In this example, the key for the Annotation Problem tool is the only + value in the list. + 2. In this example, the key for the Annotation Problem tool is added at the + beginning of a list of other keys. +* Select **Save Changes**. + +![An ordered (numbered) list inside an unordered (bulleted) list.](static/markdown.png) + +##### Ordered List inside Ordered List + +To include another ordered list inside an ordered list, indent the second +ordered list three spaces. The second ordered list must be flush with the text +in the numbered list. The first ordered list uses numerals, and the second +uses letters. + +1. Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be + comma separated. + 1. In this example, the key for the Annotation Problem tool is the only + value in the list. + 2. In this example, the key for the Annotation Problem tool is added at + the beginning of a list of other keys. +2. Select **Save Changes**. + +##### Code, Images, and Other Content inside Lists + +To include content such as code or an image inside a list, position the code or +image directive flush with the text in the list. That is, indent three spaces +for ordered lists and two spaces for unordered lists. + +1. In the `lms.yml` and `studio.yml` files, set the value of + `CERTIFICATES_HTML_VIEW` within the `FEATURES` object to `true`. + ```bash + "FEATURES": { + ... + 'CERTIFICATES_HTML_VIEW': true, + ... + } + ``` +2. Save the `lms.yml` and `studio.yml` files. + +### Conditional Text + +To conditionalize a single paragraph, use either the `only:: Partners` or +the `only:: Open_edX` directive, and indent the paragraph under the +directive. You can add the conditional text as regular text or as a note. + +Make sure to indent the paragraph under the directive. + +To conditionalize more than a paragraph, use either the `only:: Partners` or +the `only:: Open_edX` directive, and then use an `include::` directive +indented under the only directive. + +### Notes and Warnings + +``` +.. note:: + This is note text. If note text runs over a line, make sure the lines wrap + and are indented to the same level as the note tag. If formatting is + incorrect, part of the note might not render in the HTML output. + + Notes can have more than one paragraph. Successive paragraphs must indent + to the same level as the rest of the note. +``` + +> ###### NOTE +> +> This is note text. If note text runs over a line, make sure the lines wrap +> and are indented to the same level as the note tag. If formatting is +> incorrect, part of the note might not render in the HTML output. +> +> Notes can have more than one paragraph. Successive paragraphs must indent to +> the same level as the rest of the note. + +``` +.. warning:: + Warnings are formatted in the same way as notes. In the same way, lines + must be broken and indented under the warning tag. +``` + +> ###### WARNING +> +> Warnings are formatted in the same way as notes. In the same way, lines must +> be broken and indented under the warning tag. + +### Cross-References + +In edX documents, you can include cross-references to other locations in the +same edX document, to locations in other edX documents (such as a cross- +reference from a location in the *Building and Running an edX Course* guide to +a location in the *EdX Learner’s Guide*), to JIRA stories, and to external +websites. In this section, “EdX documents” refers to the resources, including +guides and tutorials, that are listed on docs.edx.org. + +For more information about creating cross-references using RST and Sphinx, see +[Cross-referencing arbitrary locations](http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations) in the online Sphinx documentation. + +#### Cross-References to Locations in the Same Document + +Cross-references to locations in the same document use anchors that are located +above the heading for each topic or section. Anchors can contain numbers, +letters, spaces, underscores, and hyphens, but cannot include punctuation. +Anchors use the following syntax. + +``` +.. _Anchor Text: +``` + +The following example shows an anchor for a section, followed by the heading +for that section. `SFD SN Keyboard Shortcuts` is the anchor text. + +##### Keyboard Shortcuts for Notes + +To create cross-references to locations in the same document, you can use the +anchor only, or you can use your own text. The anchor text is never visible in +output. It is replaced by the text of the heading that follows the anchor or +the text that you specify. + +##### Cross-References Using the Anchor Only + +To add a cross-reference to a specific location in a document and use the text +of the heading for that location as link text, use `:ref:`Anchor Text`` +syntax, as in the following example. + +For more information about using keyboard shortcuts, see SFD SN Keyboard Shortcuts. + +In this example, “SFD SN Keyboard Shortcuts” is the anchor text for a section +that is titled “Keyboard Shortcuts for Notes”. Readers will see the following +text, and “Keyboard Shortcuts for Notes” will be an active link. + +``` +For more information about using keyboard shortcuts, see Keyboard Shortcuts +for Notes. +``` + +##### Cross-References Using Specified Link Text + +For internal cross-references that use text other than the heading for the +section that you’re linking to, use `:ref:`specified text`` +syntax, as in the following example. + +If you want to, you can use keyboard shortcuts to create, edit, and view notes. + +> ###### NOTE +> +> Do not include a space between the last word of the link text and the opening +> angle bracket for the anchor text. + +In this example, “keyboard shortcuts” is the link text, and “SFD SN Keyboard +Shortcuts” is the anchor text for a section that is titled “Keyboard Shortcuts +for Notes”. Readers will see the following text, and “keyboard shortcuts” will +be an active link. + +``` +If you want to, you can use keyboard shortcuts to create, edit, and view your +notes. +``` + +#### Cross-References to Locations in Different edX Documents + +You can create cross-references between different edX documents. For example, +you can create a link in *Building and Running an edX Course* to a topic in the +*EdX Learner’s Guide*. To do this, you use the intersphinx map ID of the +document that you want to link to and the anchor text for the section you want. +The cross-reference uses the following syntax. + +``` +:ref:`intersphinx_map_ID:Anchor Name` +``` + +For example: + +partnercoursestaff:Release Dates + +To find the intersphinx map ID for the document that you want, follow these +steps. + +1. Open the conf.py file in the [edx-documentation/shared](https://github.com/openedx/edx-documentation/blob/master/shared/conf.py) folder, and then + locate the following line. + + `intersphinx_mapping = {` +2. In the list that follows this line, find the ID for the document that you + want. The text between the single quotation marks (’) at the beginning of + each line is the intersphinx map ID for the document. + +The following intersphinx map IDs are the most frequently used. + +| Map ID | Document | +|-----------------------|--------------------------------------------------------------| +| `partnercoursestaff` | *Building and Running an edX Course* | +| `opencoursestaff` | *Building and Running an Open edX Course* | +| `learners` | *EdX Learner’s Guide* | +| `openlearners` | *Open edX Learner’s Guide* | +| `data` | *EdX Research Guide* | +| `insights` | *Using edX Insights* | +| `installation` | *Installing, Configuring, and Running the Open edX Platform* | +| `opendevelopers` | *Open edX Developer’s Guide* | +| `partnerreleasenotes` | Partner release notes | +| `openreleasenotes` | Open edX release notes | + +#### Cross-References to External Web Pages + +A cross-reference to an external web page has several elements. + +* The URL of the external web page. +* The text to use for the cross-reference. This text becomes an anchor in the + file that contains the cross-reference. +* An `include` directive in the file that contains the cross-reference to the + links.rst file that is located in the `edx-documentation/en_us/links/` + folder. +* An entry in the links.rst file. + +To create an external cross-reference, follow these steps. + +1. In the paragraph where you want the cross-reference, add the text that you + want to use for the link, formatted as follows (where “Release Pages” is the + link text). This creates an anchor out of that text. + ``` + The edX engineering wiki `Release Pages`_ provide access to detailed + information about every change made to the edx-platform GitHub + repository. + ``` +2. In the file that contains the cross-reference, add an `include` directive + for the `edx-documentation/en_us/links/links.rst` file if one does not + already exist. These `include` directives are typically at the end of the + file. + ``` + .. include:: ../../links/links.rst + ``` + + > ###### NOTE + > + > The path to the links.rst file depends on the location of the file where + > you are creating the link. For example, the path might be + > `../../../links/links.rst` or `../links/links.rst`. +3. In the `edx-documentation/en_us/links/links.rst` file, add an entry for + the anchor text and the URL of the external website, formatted as follows. + Make sure that the anchor text in this file matches the anchor text in the + file that contains the cross-reference exactly, including capitalization. + ``` + .. _Release Pages: https://openedx.atlassian.net/wiki/display/ENG/Release+Pages + ``` + +Readers will see the following text. “Release Pages” will be an active link. + +``` +The edX engineering wiki Release Pages provide access to detailed +information about every change made to the edx-platform GitHub +repository. +``` + +The edX engineering wiki [Release Pages](https://openedx.atlassian.net/wiki/pages/viewpage.action?pageId=12550314) provide access to detailed +information about every change made to the edx-platform GitHub +repository. + +### Image References + +Image references look like this. + +![A screen capture showing the elements of the course outline in the LMS.](static/markdown.png) + +Image links can include optional specifications such as height, width, or +scale. Alternative text for screen readers is required for each image. Provide +text that is useful to someone who might not be able to see the image. + +### Tables + +Each example in this section shows the raw formatting for the table followed +by the table as it would render (if you are viewing this file as part of the +Style Guide). + +#### Example of a table with an empty cell + +The empty cell is the second column in the first row of this table. + +``` +.. list-table:: + :widths: 25 25 50 + + * - Annotation Problem + - + - Annotation problems ask students to respond to questions about a + specific block of text. The question appears above the text when the + student hovers the mouse over the highlighted text so that students can + think about the question as they read. + * - Example Poll + - Conditional Module + - You can create a conditional module to control versions of content that + groups of students see. For example, students who answer "Yes" to a + poll question then see a different block of text from the students who + answer "No" to that question. + * - Example JavaScript Problem + - Custom JavaScript + - Custom JavaScript display and grading problems (also called *custom + JavaScript problems* or *JS input problems*) allow you to create a + custom problem or tool that uses JavaScript and then add the problem or + tool directly into Studio. +``` + +| Annotation Problem | | Annotation problems ask students to respond to questions about a
specific block of text. The question appears above the text when the
student hovers the mouse over the highlighted text so that students can
think about the question as they read. | +|----------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Example Poll | Conditional Module | You can create a conditional module to control versions of content that
groups of students see. For example, students who answer “Yes” to a
poll question then see a different block of text from the students who
answer “No” to that question. | +| Exampel JavaScript Problem | Custom JavaScript | Custom JavaScript display and grading problems (also called *custom
JavaScript problems* or *JS input problems*) allow you to create a
custom problem or tool that uses JavaScript and then add the problem or
tool directly into Studio. | + +#### Example of a table with a header row + +``` +.. list-table:: + :widths: 15 15 70 + :header-rows: 1 + + * - First Name + - Last Name + - Residence + * - Elizabeth + - Bennett + - Longbourne + * - Fitzwilliam + - Darcy + - Pemberley +``` + +| First Name | Last Name | Residence | +|--------------|-------------|-------------| +| Elizabeth | Bennett | Longbourne | +| Fitzwilliam | Darcy | Pemberley | + +#### Example of a table with a boldface first column + +``` +.. list-table:: + :widths: 15 15 70 + :stub-columns: 1 + + * - First Name + - Elizabeth + - Fitzwilliam + * - Last Name + - Bennett + - Darcy + * - Residence + - Longboure + - Pemberley +``` + +| First Name | Elizabeth | Fitzwilliam | +|--------------|-------------|---------------| +| Last Name | Bennett | Darcy | +| Residence | Longboure | Pemberley | + +#### Example of a table with a cell that includes an unordered list + +The blank lines before and after the unordered list are critical for the list +to render correctly. + +``` +.. list-table:: + :widths: 15 15 60 + :header-rows: 1 + + * - Field + - Type + - Details + * - ``correct_map`` + - dict + - For each problem ID value listed by ``answers``, provides: + + * ``correctness``: string; 'correct', 'incorrect' + * ``hint``: string; Gives optional hint. Nulls allowed. + * ``hintmode``: string; None, 'on_request', 'always'. Nulls allowed. + * ``msg``: string; Gives extra message response. + * ``npoints``: integer; Points awarded for this ``answer_id``. Nulls allowed. + * ``queuestate``: dict; None when not queued, else ``{key:'', time:''}`` + where ``key`` is a secret string dump of a DateTime object in the form + '%Y%m%d%H%M%S'. Nulls allowed. + + * - ``grade`` + - integer + - Current grade value. + * - ``max_grade`` + - integer + - Maximum possible grade value. +``` + +| Field | Type | Details | +|---------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `correct_map` | dict | For each problem ID value listed by `answers`, provides:

* `correctness`: string; ‘correct’, ‘incorrect’
* `hint`: string; Gives optional hint. Nulls allowed.
* `hintmode`: string; None, ‘on_request’, ‘always’. Nulls allowed.
* `msg`: string; Gives extra message response.
* `npoints`: integer; Points awarded for this `answer_id`. Nulls allowed.
* `queuestate`: dict; None when not queued, else `{key:'', time:''}`
where `key` is a secret string dump of a DateTime object in the form
‘%Y%m%d%H%M%S’. Nulls allowed. | +| `grade` | integer | Current grade value. | +| `max_grade` | integer | Maximum possible grade value. | + +### Code Formatting + +#### Inline code + +In inline text, any text can be formatted as code (monospace font) by +enclosing the selection within a pair of double “grave accent” characters (\`). +For example, ```these words``` are formatted in a monospace font when the +documentation is output as PDF or HTML. + +#### Code blocks + +To set text in a code block, end the previous paragaph with 2 colons, leave +one line before the intended code block, and make sure the code block is +indented beyond the first colon. + +``` +For example, this is the introductory paragraph +:: + +

and this is the code block following.

+``` + +Alternatively, use the code-block tag. Optionally, indicate the type of code +after the 2 colons in the tag, which results in the tags within the code block +being displayed in different colors. + +```xml + + + + PLACEHOLDER: Text of annotation + PLACEHOLDER: Text of question + PLACEHOLDER: Type your response below: + PLACEHOLDER: In your response to this question, which tag below + do you choose? + + + + + + + + +

PLACEHOLDER: Detailed explanation of solution

+ + +``` + +## Using the Learner Engagement Report + +With the learner engagement report, you can monitor what individual learners +are doing in your course. The report contains a row for each enrolled learner, +and has columns that quantify overall course activity and engagement with +course problems, videos, discussions, and textbooks. + +With this report, you can identify which learners are, and which are not, +visiting course content. Further, you can identify the learners who are +attempting problems, playing videos, participating in discussions, or viewing +textbooks. + +The server generates a new learner engagement report every day for the +previous day’s activity. On Mondays, an additional report is generated to +summarize activity during the previous week (Monday through Sunday). + +> * [Understanding the Learner Engagement Report](#understanding-the-learner-engagement-report) +> * [Reported Problem Types](#reported-problem-types) +> * [Report Columns](#report-columns) +> * [Download the Learner Engagement Report](#download-the-learner-engagement-report) + +### Understanding the Learner Engagement Report + +#### Reported Problem Types + +To measure problem-related activity, the learner engagement report includes +data for capa problems. That is, the report includes data for problems for +which learners can select **Check**, including these problem types. + +> * Checkboxes +> * Custom JavaScript +> * Drag and Drop +> * Dropdown +> * Math expression input +> * Multiple choice +> * Numerical input +> * Text input + +The report does not include data for open response assessments or LTI +components. + +For more information about the problem types that you can add to courses, see +Exercises and Tools Index. + +#### Report Columns + +The learner engagement report .csv files contain the following columns. + +| Column | Description | +|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| Date | Included only in the daily report. The date of the reported activity. | +| End Date | Included only in the weekly report. The last date of the report
period. | +| Course ID | The identifier for the course run. | +| Username | The unique username for an edX account. | +| Email | The unique email address for an edX account. | +| Cohort | Indicates the learner’s assigned cohort. Blank if the learner is not
assigned to a cohort. | +| Was Active | Included only in the daily report. 1 for learners who visited any page
(URL) in the course at least once during the reported day, 0 otherwise. | +| Days Active This Week | Included only in the weekly report. Identifies the number of days
during the week that the learner visited any page (URL) in the course. | +| Unique Problems Attempted | The number of unique problems for which the learner selected **Check**
to submit an answer. | +| Total Problem Attempts | The number of times the learner selected **Check** to submit answers,
regardless of the particular problem attempted. | +| Unique Problems Correct | The number of unique problems for which the learner submitted a correct
answer. | +| Unique Videos Played | The number of times the learner played a video. Each video that the
learner began to play is included in this count once. | +| Discussion Posts | The number of new posts the learner contributed to the course
discussions. | +| Discussion Responses | The number of responses the learner made to posts in the course
discussions. | +| Discussion Comments | The number of comments the learner made on responses in the course
discussions. | +| Textbook Pages Viewed | The number of pages in a .pdf textbook that the learner viewed. | +| URL of Last Subsection Viewed | The URL of the last subsection the learner visited. | + +### Download the Learner Engagement Report + +An automated process runs daily on the system server to update learner +engagement data and create the daily or weekly .csv file for you to download. +Links to the .csv files are available on the Instructor Dashboard. + +To download a learner engagement report, follow these steps. + +1. View the live version of your course. +2. Select **Instructor**, then select **Data Download**. +3. At the bottom of the page, select the + `student_engagement_daily_{date}.csv` or `student_engagement_weekly_{end + date}.csv` file name. You might have to scroll down to find a specific + file. + +## Welcome to Sphinx-Markdown-Builder TocTree Test’s documentation! + +### Documentation + +Some link to a class `my_module.module_class.ModuleClass` + +## my_module + +Example module + +#### Sub Modules + +#### Classes and Functions + +#### *class* Point(x, y) + +A Point + +### Attributes + +x: int +: The x value + +y: str +: The y value + +##### x *: int* + +X value + +##### y *: str* + +Y value + +* **Parameters:** + * **x** (*int*) + * **y** (*str*) + +#### deprecated_function() + +Some old function. + +##### Deprecated +Deprecated since version 3.1: Use `other()` instead. + +#### func1(param1) + +This is a function with a single parameter. +Thanks to github.com/remiconnesson. + +* **Parameters:** + **param1** (*int*) – This is a single parameter. +* **Return type:** + int + +#### func2(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – This is the first parameter. + * **param2** (*int*) – This is the second parameter. +* **Return type:** + str + +#### func3(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – Alice [^1]. + * **param2** (*int*) – Bon [^2]. + +### References + +[^1]: Alice is commonly used to describe the first actor. +[^2]: Bob is commonly used to describe the second actor. + +## my_module.module_class + +A module class file. + +#### Classes and Functions + +#### default_var *= 'some_default_value'* + +A default variable to be used by `SubmoduleClass` + +#### *class* ModuleClass + +A class inside a module. + +Initialize a module class object + +##### function(param1, param2) + +Do nothing + +This is a dummy function that does not do anything. + +* **Parameters:** + * **param1** (*int*) – Does nothing + * **param2** (*str*) – Does nothing as well +* **Returns:** + Nothing. +* **Return type:** + None + +> ###### SEE ALSO +> +> `function()` + +## my_module.submodule + +Example sub-module + +#### Sub Modules + +#### Classes and Functions + +## my_module.submodule.my_class + +A submodule class file. + +#### Classes and Functions + +#### *class* SubmoduleClass(var) + +A class inside a submodule. + +* **Parameters:** + **var** (*str*) – Does nothing + +##### function(param1, param2) + +Do nothing + +This is a dummy function that does not do anything. + +* **Parameters:** + * **param1** (*int*) – Does nothing + * **param2** (*str*) – Does nothing as well +* **Returns:** + Nothing. +* **Return type:** + None + +## Math Example + +Formula 1 +: Definition of the formula as inline math: + $\frac{ \sum_{t=0}^{N}f(t,k) }{N}$. +
+ Some more text related to the definition. + +Display math: + +$$ +\frac{ \sum_{t=0}^{N}f(t,k) }{N} +$$ + +## Code Example + +```pycon +>>> print("this is a Doctest block.") +this is a Doctest block. +``` + +## Line Block + +text +sub text +
+more text +
+
+
+ +### Other text + +other text + +### Referencing terms from a glossary + +Some other text that refers to Glossary2-Term2. + +### Http domain directive + +#### GET /users/(*int:* user_id)/posts/(tag) + +### C domain + +#### PyObject \*PyType_GenericAlloc(PyTypeObject \*type, Py_ssize_t nitems) + +## Test Image With Target + +[![image](static/markdown.png)](https://github.com/liran-funaro/sphinx-markdown-builder) + +Download [`this example image`](/static/markdown.png). + +![image](static/markdown.png) + +## Empty package + +## Glossary test for multiple glossaries + +### Section for first glossary + + + +Glossary1-Term1 +: Some random text for term 1 in glossary 1. + + + +Glossary1-Term2 +: Some random text for term 2 in glossary 1. Referencing Glossary1-Term1. + + + +Glossary1-Term3 +: Some random text for term 3 in glossary 1. Referencing Glossary3-Term1. + +### Section for second glossary + + + +Glossary2-Term1 +: Some random text for term 1 in glossary 2. + + + +Glossary2-Term2 +: Some random text for term 2 in glossary 2. Some reference for Glossary1-Term3. + +### Section for third glossary + + + +Glossary3-Term1 +: Some random text for term 1 in glossary 3. + +## Auto Module + +Example module + +#### *class* Point(x, y) + +A Point + +### Attributes + +x: int +: The x value + +y: str +: The y value + +##### x *: int* + +X value + +##### y *: str* + +Y value + +* **Parameters:** + * **x** (*int*) + * **y** (*str*) + +#### deprecated_function() + +Some old function. + +##### Deprecated +Deprecated since version 3.1: Use `other()` instead. + +#### func1(param1) + +This is a function with a single parameter. +Thanks to github.com/remiconnesson. + +* **Parameters:** + **param1** (*int*) – This is a single parameter. +* **Return type:** + int + +#### func2(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – This is the first parameter. + * **param2** (*int*) – This is the second parameter. +* **Return type:** + str + +#### func3(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – Alice [^1]. + * **param2** (*int*) – Bon [^2]. + +### References + +[^1]: Alice is commonly used to describe the first actor. +[^2]: Bob is commonly used to describe the second actor. diff --git a/tests/expected/overrides-auto-module.md b/tests/expected/overrides-auto-module.md index 7ae9d13..0b23b6d 100644 --- a/tests/expected/overrides-auto-module.md +++ b/tests/expected/overrides-auto-module.md @@ -57,12 +57,12 @@ This is a function with two parameters. This is a function with two parameters. * **Parameters:** - - **param1** – Alice [1](#id3). - - **param2** – Bon [2](#id4). + - **param1** – Alice [^1]. + - **param2** – Bon [^2]. ## References -* **[1]** Alice is commonly used to describe the first actor. -* **[2]** Bob is commonly used to describe the second actor. +[^1]: Alice is commonly used to describe the first actor. +[^2]: Bob is commonly used to describe the second actor. diff --git a/tests/expected/single.md b/tests/expected/single.md new file mode 100644 index 0000000..3a50a7f --- /dev/null +++ b/tests/expected/single.md @@ -0,0 +1,1142 @@ +# sphinx_markdown_builder Documentation + +## Table of Contents + +* [Main Document](#index) +* [Examplerstfile](#ExampleRSTFile) +* [Section Course Student](#Section_course_student) +* [Links](#links) +* [Auto Summery](#auto-summery) +* [My Module](#library/my_module) +* [My Module.Module Class](#library/my_module.module_class) +* [My Module.Submodule](#library/my_module.submodule) +* [My Module.Submodule.My Class](#library/my_module.submodule.my_class) +* [Blocks](#blocks) +* [Image Target](#image-target) +* [Empty](#empty) +* [Glossaries](#glossaries) +* [Auto Module](#auto-module) + + + + +## Main Test File + + + + + + + + + +## Example .rst File + +If you work with edX documentation source files, you might find this file +helpful as a reference. This file contains examples of .rst formatting. + +Explanations and more context for each type of element are provided in +“Work with edX Documentation Source Files”. + +This file covers the following topics. + +> ###### Table of content +> +> * [Heading Levels](#heading-levels) +> * [Paragraph Text and Commented Text](#paragraph-text-and-commented-text) +> * [Ordered and Unordered Lists](#ordered-and-unordered-lists) +> * [Conditional Text](#conditional-text) +> * [Notes and Warnings](#notes-and-warnings) +> * [Cross-References](#cross-references) +> * [Image References](#image-references) +> * [Tables](#tables) +> * [Code Formatting](#code-formatting) +> * [Links](#links) + +### Heading Levels + +The top of the document is heading 1, and this section is heading 2. The following are the rest of the headers. + +#### Heading 3 + +##### Heading 4 + +###### Heading 5 + +###### Heading 6 + +### Paragraph Text and Commented Text + +This is an example of regular text in paragraph form. There are no indents. As +a best practice, break lines at about 80 characters, so that each line has its +own line number for commenting in reviews. + +> ###### WARNING +> +> Throughout text and code examples, make sure double quotation +> marks and apostrophes are straight (”) or (‘), not curly quotatation marks +> and apostrophes, which might be introduced when text is cut and pasted from +> other sources or editors. + +> ###### ATTENTION +> +> Boldface is used for labels that are visible in the user interface. The UI +> text is surrounded by double asterisks. For example, **bold**. + +> ###### IMPORTANT +> +> This is an important message. + +> ###### HINT +> +> This is a hint message. + +Italics are rarely used. Text surrounded by single asterisks is rendered in +*italics*. + +Monospace text is used for `code examples`. Text surrounded by double grave +accent characters is rendered in monospace font. + + + +In English source files, look for comments addressed to translators from writers. + +`.. Translators: In this code example, do not translate such and such.` + + + +### Ordered and Unordered Lists + +Use hash symbols for ordered lists. + +1. Select **Advanced Settings**. +2. Find the **Course Advertised Start Date** policy key. +3. Enter the value you want to display. + +> ###### NOTE +> +> Ordered lists usually use numerals. Nested ordered lists (ordered lists inside +> other ordered lists) use letters. + +Use asterisks for unordered (bulleted) lists. + +* Who is teaching the course? +* What university or college is the course affiliated with? +* What topics and concepts are covered in your course? +* Why should a learner enroll in your course? + +#### Nested Lists or Content + +You can include content including additional lists and code examples inside +lists. + +##### Unordered List inside Ordered List + +To include an unordered list inside an ordered list, indent the unordered list +three spaces. The first bullet in the unordered list must be flush with the +text in the ordered list. + +1. Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be + comma separated. + * In this example, the key for the Annotation Problem tool is the only + value in the list. + * In this example, the key for the Annotation Problem tool is added at + the beginning of a list of other keys. +2. Select **Save Changes**. + +![An unordered (bulleted) list inside an ordered (numbered) list.](static/markdown.png) + +##### Ordered List inside Unordered List + +To include an ordered list inside an unordered list, indent the ordered list +two spaces. The first number or letter of the ordered list must be flush with +the text in the unordered list. + +* Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be comma + separated. + 1. In this example, the key for the Annotation Problem tool is the only + value in the list. + 2. In this example, the key for the Annotation Problem tool is added at the + beginning of a list of other keys. +* Select **Save Changes**. + + + + + +##### Unordered List inside Unordered List + +To include an unordered list inside another unordered list, indent the second +unordered list two spaces. The first bullet of the second unordered list must +be flush with the text in the unordered list. + +* Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be + comma separated. + 1. In this example, the key for the Annotation Problem tool is the only + value in the list. + 2. In this example, the key for the Annotation Problem tool is added at the + beginning of a list of other keys. +* Select **Save Changes**. + +![An ordered (numbered) list inside an unordered (bulleted) list.](static/markdown.png) + +##### Ordered List inside Ordered List + +To include another ordered list inside an ordered list, indent the second +ordered list three spaces. The second ordered list must be flush with the text +in the numbered list. The first ordered list uses numerals, and the second +uses letters. + +1. Review your entry to verify that the key is accurate and that it is + surrounded by quotation marks. If there is a list of keys, they must be + comma separated. + 1. In this example, the key for the Annotation Problem tool is the only + value in the list. + 2. In this example, the key for the Annotation Problem tool is added at + the beginning of a list of other keys. +2. Select **Save Changes**. + + + + + +##### Code, Images, and Other Content inside Lists + +To include content such as code or an image inside a list, position the code or +image directive flush with the text in the list. That is, indent three spaces +for ordered lists and two spaces for unordered lists. + +1. In the `lms.yml` and `studio.yml` files, set the value of + `CERTIFICATES_HTML_VIEW` within the `FEATURES` object to `true`. + ```bash + "FEATURES": { + ... + 'CERTIFICATES_HTML_VIEW': true, + ... + } + ``` +2. Save the `lms.yml` and `studio.yml` files. + +### Conditional Text + +To conditionalize a single paragraph, use either the `only:: Partners` or +the `only:: Open_edX` directive, and indent the paragraph under the +directive. You can add the conditional text as regular text or as a note. + +Make sure to indent the paragraph under the directive. + +Data about course enrollment is available from edX Insights. You can access +Insights from the instructor dashboard for your live course: after you select +**Instructor**, follow the link in the banner at the top of each page. For +more information, see [Using edX Insights](http://edx.readthedocs.io/projects/edx-insights/en/latest/). + +To conditionalize more than a paragraph, use either the `only:: Partners` or +the `only:: Open_edX` directive, and then use an `include::` directive +indented under the only directive. + +### Notes and Warnings + +``` +.. note:: + This is note text. If note text runs over a line, make sure the lines wrap + and are indented to the same level as the note tag. If formatting is + incorrect, part of the note might not render in the HTML output. + + Notes can have more than one paragraph. Successive paragraphs must indent + to the same level as the rest of the note. +``` + +> ###### NOTE +> +> This is note text. If note text runs over a line, make sure the lines wrap +> and are indented to the same level as the note tag. If formatting is +> incorrect, part of the note might not render in the HTML output. +> +> Notes can have more than one paragraph. Successive paragraphs must indent to +> the same level as the rest of the note. + +``` +.. warning:: + Warnings are formatted in the same way as notes. In the same way, lines + must be broken and indented under the warning tag. +``` + +> ###### WARNING +> +> Warnings are formatted in the same way as notes. In the same way, lines must +> be broken and indented under the warning tag. + +### Cross-References + +In edX documents, you can include cross-references to other locations in the +same edX document, to locations in other edX documents (such as a cross- +reference from a location in the *Building and Running an edX Course* guide to +a location in the *EdX Learner’s Guide*), to JIRA stories, and to external +websites. In this section, “EdX documents” refers to the resources, including +guides and tutorials, that are listed on docs.edx.org. + +For more information about creating cross-references using RST and Sphinx, see +[Cross-referencing arbitrary locations](http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations) in the online Sphinx documentation. + +#### Cross-References to Locations in the Same Document + +Cross-references to locations in the same document use anchors that are located +above the heading for each topic or section. Anchors can contain numbers, +letters, spaces, underscores, and hyphens, but cannot include punctuation. +Anchors use the following syntax. + +``` +.. _Anchor Text: +``` + +The following example shows an anchor for a section, followed by the heading +for that section. `SFD SN Keyboard Shortcuts` is the anchor text. + + + +##### Keyboard Shortcuts for Notes + +To create cross-references to locations in the same document, you can use the +anchor only, or you can use your own text. The anchor text is never visible in +output. It is replaced by the text of the heading that follows the anchor or +the text that you specify. + +##### Cross-References Using the Anchor Only + +To add a cross-reference to a specific location in a document and use the text +of the heading for that location as link text, use `:ref:`Anchor Text`` +syntax, as in the following example. + +For more information about using keyboard shortcuts, see SFD SN Keyboard Shortcuts. + +In this example, “SFD SN Keyboard Shortcuts” is the anchor text for a section +that is titled “Keyboard Shortcuts for Notes”. Readers will see the following +text, and “Keyboard Shortcuts for Notes” will be an active link. + +``` +For more information about using keyboard shortcuts, see Keyboard Shortcuts +for Notes. +``` + +##### Cross-References Using Specified Link Text + +For internal cross-references that use text other than the heading for the +section that you’re linking to, use `:ref:`specified text`` +syntax, as in the following example. + +If you want to, you can use keyboard shortcuts to create, edit, and view notes. + +> ###### NOTE +> +> Do not include a space between the last word of the link text and the opening +> angle bracket for the anchor text. + +In this example, “keyboard shortcuts” is the link text, and “SFD SN Keyboard +Shortcuts” is the anchor text for a section that is titled “Keyboard Shortcuts +for Notes”. Readers will see the following text, and “keyboard shortcuts” will +be an active link. + +``` +If you want to, you can use keyboard shortcuts to create, edit, and view your +notes. +``` + +#### Cross-References to Locations in Different edX Documents + +You can create cross-references between different edX documents. For example, +you can create a link in *Building and Running an edX Course* to a topic in the +*EdX Learner’s Guide*. To do this, you use the intersphinx map ID of the +document that you want to link to and the anchor text for the section you want. +The cross-reference uses the following syntax. + +``` +:ref:`intersphinx_map_ID:Anchor Name` +``` + +For example: + +partnercoursestaff:Release Dates + +To find the intersphinx map ID for the document that you want, follow these +steps. + +1. Open the conf.py file in the [edx-documentation/shared](https://github.com/openedx/edx-documentation/blob/master/shared/conf.py) folder, and then + locate the following line. + + `intersphinx_mapping = {` +2. In the list that follows this line, find the ID for the document that you + want. The text between the single quotation marks (’) at the beginning of + each line is the intersphinx map ID for the document. + +The following intersphinx map IDs are the most frequently used. + +| Map ID | Document | +|-----------------------|--------------------------------------------------------------| +| `partnercoursestaff` | *Building and Running an edX Course* | +| `opencoursestaff` | *Building and Running an Open edX Course* | +| `learners` | *EdX Learner’s Guide* | +| `openlearners` | *Open edX Learner’s Guide* | +| `data` | *EdX Research Guide* | +| `insights` | *Using edX Insights* | +| `installation` | *Installing, Configuring, and Running the Open edX Platform* | +| `opendevelopers` | *Open edX Developer’s Guide* | +| `partnerreleasenotes` | Partner release notes | +| `openreleasenotes` | Open edX release notes | + + + +#### Cross-References to External Web Pages + +A cross-reference to an external web page has several elements. + +* The URL of the external web page. +* The text to use for the cross-reference. This text becomes an anchor in the + file that contains the cross-reference. +* An `include` directive in the file that contains the cross-reference to the + links.rst file that is located in the `edx-documentation/en_us/links/` + folder. +* An entry in the links.rst file. + +To create an external cross-reference, follow these steps. + +1. In the paragraph where you want the cross-reference, add the text that you + want to use for the link, formatted as follows (where “Release Pages” is the + link text). This creates an anchor out of that text. + ``` + The edX engineering wiki `Release Pages`_ provide access to detailed + information about every change made to the edx-platform GitHub + repository. + ``` +2. In the file that contains the cross-reference, add an `include` directive + for the `edx-documentation/en_us/links/links.rst` file if one does not + already exist. These `include` directives are typically at the end of the + file. + ``` + .. include:: ../../links/links.rst + ``` + + > ###### NOTE + > + > The path to the links.rst file depends on the location of the file where + > you are creating the link. For example, the path might be + > `../../../links/links.rst` or `../links/links.rst`. +3. In the `edx-documentation/en_us/links/links.rst` file, add an entry for + the anchor text and the URL of the external website, formatted as follows. + Make sure that the anchor text in this file matches the anchor text in the + file that contains the cross-reference exactly, including capitalization. + ``` + .. _Release Pages: https://openedx.atlassian.net/wiki/display/ENG/Release+Pages + ``` + +Readers will see the following text. “Release Pages” will be an active link. + +``` +The edX engineering wiki Release Pages provide access to detailed +information about every change made to the edx-platform GitHub +repository. +``` + +The edX engineering wiki [Release Pages](https://openedx.atlassian.net/wiki/pages/viewpage.action?pageId=12550314) provide access to detailed +information about every change made to the edx-platform GitHub +repository. + +### Image References + +Image references look like this. + +![A screen capture showing the elements of the course outline in the LMS.](static/markdown.png) + +Image links can include optional specifications such as height, width, or +scale. Alternative text for screen readers is required for each image. Provide +text that is useful to someone who might not be able to see the image. + + + +### Tables + +Each example in this section shows the raw formatting for the table followed +by the table as it would render (if you are viewing this file as part of the +Style Guide). + +#### Example of a table with an empty cell + +The empty cell is the second column in the first row of this table. + +``` +.. list-table:: + :widths: 25 25 50 + + * - Annotation Problem + - + - Annotation problems ask students to respond to questions about a + specific block of text. The question appears above the text when the + student hovers the mouse over the highlighted text so that students can + think about the question as they read. + * - Example Poll + - Conditional Module + - You can create a conditional module to control versions of content that + groups of students see. For example, students who answer "Yes" to a + poll question then see a different block of text from the students who + answer "No" to that question. + * - Example JavaScript Problem + - Custom JavaScript + - Custom JavaScript display and grading problems (also called *custom + JavaScript problems* or *JS input problems*) allow you to create a + custom problem or tool that uses JavaScript and then add the problem or + tool directly into Studio. +``` + +| Annotation Problem | | Annotation problems ask students to respond to questions about a
specific block of text. The question appears above the text when the
student hovers the mouse over the highlighted text so that students can
think about the question as they read. | +|----------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Example Poll | Conditional Module | You can create a conditional module to control versions of content that
groups of students see. For example, students who answer “Yes” to a
poll question then see a different block of text from the students who
answer “No” to that question. | +| Exampel JavaScript Problem | Custom JavaScript | Custom JavaScript display and grading problems (also called *custom
JavaScript problems* or *JS input problems*) allow you to create a
custom problem or tool that uses JavaScript and then add the problem or
tool directly into Studio. | + +#### Example of a table with a header row + +``` +.. list-table:: + :widths: 15 15 70 + :header-rows: 1 + + * - First Name + - Last Name + - Residence + * - Elizabeth + - Bennett + - Longbourne + * - Fitzwilliam + - Darcy + - Pemberley +``` + +| First Name | Last Name | Residence | +|--------------|-------------|-------------| +| Elizabeth | Bennett | Longbourne | +| Fitzwilliam | Darcy | Pemberley | + +#### Example of a table with a boldface first column + +``` +.. list-table:: + :widths: 15 15 70 + :stub-columns: 1 + + * - First Name + - Elizabeth + - Fitzwilliam + * - Last Name + - Bennett + - Darcy + * - Residence + - Longboure + - Pemberley +``` + +| First Name | Elizabeth | Fitzwilliam | +|--------------|-------------|---------------| +| Last Name | Bennett | Darcy | +| Residence | Longboure | Pemberley | + +#### Example of a table with a cell that includes an unordered list + +The blank lines before and after the unordered list are critical for the list +to render correctly. + +``` +.. list-table:: + :widths: 15 15 60 + :header-rows: 1 + + * - Field + - Type + - Details + * - ``correct_map`` + - dict + - For each problem ID value listed by ``answers``, provides: + + * ``correctness``: string; 'correct', 'incorrect' + * ``hint``: string; Gives optional hint. Nulls allowed. + * ``hintmode``: string; None, 'on_request', 'always'. Nulls allowed. + * ``msg``: string; Gives extra message response. + * ``npoints``: integer; Points awarded for this ``answer_id``. Nulls allowed. + * ``queuestate``: dict; None when not queued, else ``{key:'', time:''}`` + where ``key`` is a secret string dump of a DateTime object in the form + '%Y%m%d%H%M%S'. Nulls allowed. + + * - ``grade`` + - integer + - Current grade value. + * - ``max_grade`` + - integer + - Maximum possible grade value. +``` + +| Field | Type | Details | +|---------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `correct_map` | dict | For each problem ID value listed by `answers`, provides:

* `correctness`: string; ‘correct’, ‘incorrect’
* `hint`: string; Gives optional hint. Nulls allowed.
* `hintmode`: string; None, ‘on_request’, ‘always’. Nulls allowed.
* `msg`: string; Gives extra message response.
* `npoints`: integer; Points awarded for this `answer_id`. Nulls allowed.
* `queuestate`: dict; None when not queued, else `{key:'', time:''}`
where `key` is a secret string dump of a DateTime object in the form
‘%Y%m%d%H%M%S’. Nulls allowed. | +| `grade` | integer | Current grade value. | +| `max_grade` | integer | Maximum possible grade value. | + +### Code Formatting + +#### Inline code + +In inline text, any text can be formatted as code (monospace font) by +enclosing the selection within a pair of double “grave accent” characters (\`). +For example, ```these words``` are formatted in a monospace font when the +documentation is output as PDF or HTML. + +#### Code blocks + +To set text in a code block, end the previous paragaph with 2 colons, leave +one line before the intended code block, and make sure the code block is +indented beyond the first colon. + +``` +For example, this is the introductory paragraph +:: + +

and this is the code block following.

+``` + +Alternatively, use the code-block tag. Optionally, indicate the type of code +after the 2 colons in the tag, which results in the tags within the code block +being displayed in different colors. + +```xml + + + + PLACEHOLDER: Text of annotation + PLACEHOLDER: Text of question + PLACEHOLDER: Type your response below: + PLACEHOLDER: In your response to this question, which tag below + do you choose? + + + + + + + + +

PLACEHOLDER: Detailed explanation of solution

+ + +``` + + + + +### Links + + + + + + + + + + + + + + + + + +## Using the Learner Engagement Report + +With the learner engagement report, you can monitor what individual learners +are doing in your course. The report contains a row for each enrolled learner, +and has columns that quantify overall course activity and engagement with +course problems, videos, discussions, and textbooks. + +With this report, you can identify which learners are, and which are not, +visiting course content. Further, you can identify the learners who are +attempting problems, playing videos, participating in discussions, or viewing +textbooks. + +The server generates a new learner engagement report every day for the +previous day’s activity. On Mondays, an additional report is generated to +summarize activity during the previous week (Monday through Sunday). + +> * [Understanding the Learner Engagement Report](#understanding-the-learner-engagement-report) +> * [Reported Problem Types](#reported-problem-types) +> * [Report Columns](#report-columns) +> * [Download the Learner Engagement Report](#download-the-learner-engagement-report) + +### Understanding the Learner Engagement Report + +#### Reported Problem Types + +To measure problem-related activity, the learner engagement report includes +data for capa problems. That is, the report includes data for problems for +which learners can select **Check**, including these problem types. + +> * Checkboxes +> * Custom JavaScript +> * Drag and Drop +> * Dropdown +> * Math expression input +> * Multiple choice +> * Numerical input +> * Text input + +The report does not include data for open response assessments or LTI +components. + +For more information about the problem types that you can add to courses, see +Exercises and Tools Index. + +#### Report Columns + +The learner engagement report .csv files contain the following columns. + +| Column | Description | +|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| Date | Included only in the daily report. The date of the reported activity. | +| End Date | Included only in the weekly report. The last date of the report
period. | +| Course ID | The identifier for the course run. | +| Username | The unique username for an edX account. | +| Email | The unique email address for an edX account. | +| Cohort | Indicates the learner’s assigned cohort. Blank if the learner is not
assigned to a cohort. | +| Was Active | Included only in the daily report. 1 for learners who visited any page
(URL) in the course at least once during the reported day, 0 otherwise. | +| Days Active This Week | Included only in the weekly report. Identifies the number of days
during the week that the learner visited any page (URL) in the course. | +| Unique Problems Attempted | The number of unique problems for which the learner selected **Check**
to submit an answer. | +| Total Problem Attempts | The number of times the learner selected **Check** to submit answers,
regardless of the particular problem attempted. | +| Unique Problems Correct | The number of unique problems for which the learner submitted a correct
answer. | +| Unique Videos Played | The number of times the learner played a video. Each video that the
learner began to play is included in this count once. | +| Discussion Posts | The number of new posts the learner contributed to the course
discussions. | +| Discussion Responses | The number of responses the learner made to posts in the course
discussions. | +| Discussion Comments | The number of comments the learner made on responses in the course
discussions. | +| Textbook Pages Viewed | The number of pages in a .pdf textbook that the learner viewed. | +| URL of Last Subsection Viewed | The URL of the last subsection the learner visited. | + +### Download the Learner Engagement Report + +An automated process runs daily on the system server to update learner +engagement data and create the daily or weekly .csv file for you to download. +Links to the .csv files are available on the Instructor Dashboard. + +To download a learner engagement report, follow these steps. + +1. View the live version of your course. +2. Select **Instructor**, then select **Data Download**. +3. At the bottom of the page, select the + `student_engagement_daily_{date}.csv` or `student_engagement_weekly_{end + date}.csv` file name. You might have to scroll down to find a specific + file. + + + + + + + + + + +## Links + + + + + + + + + + + + + + + + + + +## Welcome to Sphinx-Markdown-Builder TocTree Test’s documentation! + +### Documentation + +| `my_module` | Example module | +|---------------|------------------| + +Some link to a class `my_module.module_class.ModuleClass` + +--- + +## Indices and tables + +* genindex +* modindex +* search + + + + + +## my_module + +Example module + +#### Sub Modules + +| `module_class` | A module class file. | +|------------------|------------------------| +| `submodule` | Example sub-module | + +#### Classes and Functions + +#### *class* Point(x, y) + +A Point + +### Attributes + +x: int +: The x value + +y: str +: The y value + +##### x *: int* + +X value + +##### y *: str* + +Y value + +* **Parameters:** + * **x** (*int*) + * **y** (*str*) + +#### deprecated_function() + +Some old function. + +##### Deprecated +Deprecated since version 3.1: Use `other()` instead. + +#### func1(param1) + +This is a function with a single parameter. +Thanks to github.com/remiconnesson. + +* **Parameters:** + **param1** (*int*) – This is a single parameter. +* **Return type:** + int + +#### func2(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – This is the first parameter. + * **param2** (*int*) – This is the second parameter. +* **Return type:** + str + +#### func3(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – Alice [^1]. + * **param2** (*int*) – Bon [^2]. + +### References + +[^1]: Alice is commonly used to describe the first actor. +[^2]: Bob is commonly used to describe the second actor. + + + + + +## my_module.module_class + +A module class file. + +#### Classes and Functions + +#### default_var *= 'some_default_value'* + +A default variable to be used by `SubmoduleClass` + +#### *class* ModuleClass + +A class inside a module. + +Initialize a module class object + +##### function(param1, param2) + +Do nothing + +This is a dummy function that does not do anything. + +* **Parameters:** + * **param1** (*int*) – Does nothing + * **param2** (*str*) – Does nothing as well +* **Returns:** + Nothing. +* **Return type:** + None + +> ###### SEE ALSO +> +> `function()` + + + + + +## my_module.submodule + +Example sub-module + +#### Sub Modules + +| `my_class` | A submodule class file. | +|--------------|---------------------------| + +#### Classes and Functions + + + + + +## my_module.submodule.my_class + +A submodule class file. + +#### Classes and Functions + +#### *class* SubmoduleClass(var) + +A class inside a submodule. + +* **Parameters:** + **var** (*str*) – Does nothing + +##### function(param1, param2) + +Do nothing + +This is a dummy function that does not do anything. + +* **Parameters:** + * **param1** (*int*) – Does nothing + * **param2** (*str*) – Does nothing as well +* **Returns:** + Nothing. +* **Return type:** + None + + + + + +## Math Example + +Formula 1 +: Definition of the formula as inline math: + $\frac{ \sum_{t=0}^{N}f(t,k) }{N}$. +
+ Some more text related to the definition. + +Display math: + +$$ +\frac{ \sum_{t=0}^{N}f(t,k) }{N} +$$ + +## Code Example + +```pycon +>>> print("this is a Doctest block.") +this is a Doctest block. +``` + +## Line Block + +text +sub text +
+more text +
+
+
+ +### Other text + +other text + +### Referencing terms from a glossary + +Some other text that refers to Glossary2-Term2. + +### Http domain directive + +#### GET /users/(*int:* user_id)/posts/(tag) + +### C domain + +#### PyObject \*PyType_GenericAlloc(PyTypeObject \*type, Py_ssize_t nitems) + + + + + +## Test Image With Target + +[![image](static/markdown.png)](https://github.com/liran-funaro/sphinx-markdown-builder) + +Download [`this example image`](/static/markdown.png). + +![image](static/markdown.png) + + + + + + + +## Empty package + + + + + +## Glossary test for multiple glossaries + +### Section for first glossary + + + +Glossary1-Term1 +: Some random text for term 1 in glossary 1. + + + +Glossary1-Term2 +: Some random text for term 2 in glossary 1. Referencing Glossary1-Term1. + + + +Glossary1-Term3 +: Some random text for term 3 in glossary 1. Referencing Glossary3-Term1. + +### Section for second glossary + + + +Glossary2-Term1 +: Some random text for term 1 in glossary 2. + + + +Glossary2-Term2 +: Some random text for term 2 in glossary 2. Some reference for Glossary1-Term3. + +### Section for third glossary + + + +Glossary3-Term1 +: Some random text for term 1 in glossary 3. + + + + + +## Auto Module + +Example module + +#### *class* Point(x, y) + +A Point + +### Attributes + +x: int +: The x value + +y: str +: The y value + +##### x *: int* + +X value + +##### y *: str* + +Y value + +* **Parameters:** + * **x** (*int*) + * **y** (*str*) + +#### deprecated_function() + +Some old function. + +##### Deprecated +Deprecated since version 3.1: Use `other()` instead. + +#### func1(param1) + +This is a function with a single parameter. +Thanks to github.com/remiconnesson. + +* **Parameters:** + **param1** (*int*) – This is a single parameter. +* **Return type:** + int + +#### func2(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – This is the first parameter. + * **param2** (*int*) – This is the second parameter. +* **Return type:** + str + +#### func3(param1, param2) + +This is a function with two parameters. + +* **Parameters:** + * **param1** (*int*) – Alice [^1]. + * **param2** (*int*) – Bon [^2]. + +### References + +[^1]: Alice is commonly used to describe the first actor. +[^2]: Bob is commonly used to describe the second actor. + + diff --git a/tests/test_singlemarkdown.py b/tests/test_singlemarkdown.py new file mode 100644 index 0000000..94f0777 --- /dev/null +++ b/tests/test_singlemarkdown.py @@ -0,0 +1,604 @@ +"""Tests for the single markdown builder""" + +# pyright: reportAny=false, reportPrivateUsage=false, reportUnknownLambdaType=false + +import os +import shutil +import stat +from difflib import unified_diff +from collections.abc import Iterable +from pathlib import Path +from typing import Callable, Optional +from unittest import mock + +import pytest +from docutils import nodes +from docutils.utils import new_document +from sphinx.cmd.build import main +from sphinx.environment import BuildEnvironment + +from sphinx_markdown_builder.singlemarkdown import SingleFileMarkdownBuilder, setup + +# Base paths for integration tests +BUILD_PATH = Path("./tests/docs-build/single") +SOURCE_PATH = Path("./tests/source") +EXPECTED_SINGLE_PATH = Path("./tests/expected/single.md") + +# Test configurations for integration tests +TEST_NAMES = ["defaults", "overrides"] +SOURCE_FLAGS = [ + [], + [ + "-D", + 'markdown_http_base="https://localhost"', + "-D", + 'markdown_uri_doc_suffix=".html"', + "-D", + "markdown_docinfo=1", + "-D", + "markdown_anchor_sections=1", + "-D", + "markdown_anchor_signatures=1", + "-D", + "autodoc_typehints=signature", + ], +] +BUILD_PATH_OPTIONS = [ + BUILD_PATH, + BUILD_PATH / "overrides", +] +OPTIONS = list(zip(SOURCE_FLAGS, BUILD_PATH_OPTIONS)) + + +def _new_test_document() -> nodes.document: + return new_document("test") + + +def _configure_write_documents_builder( + builder: SingleFileMarkdownBuilder, + env: mock.MagicMock, + all_docs: dict[str, None], + found_docs: set[str], +) -> None: + env.all_docs = all_docs + env.found_docs = found_docs + builder.outdir = BUILD_PATH + os.makedirs(os.path.join(BUILD_PATH), exist_ok=True) + + +def _run_write_documents(builder: SingleFileMarkdownBuilder, open_side_effect: Optional[OSError] = None) -> None: + builder.prepare_writing = mock.MagicMock() + with mock.patch("sphinx_markdown_builder.singlemarkdown.MarkdownWriter") as mock_writer_class: + writer_mock = mock.MagicMock() + writer_mock.output = "Test output" + mock_writer_class.return_value = writer_mock + if open_side_effect is None: + builder.write_documents(set()) + return + with mock.patch("builtins.open", side_effect=open_side_effect): + builder.write_documents(set()) + + +def _clean_build_path(): + if BUILD_PATH.exists(): + shutil.rmtree(BUILD_PATH) + + +def _touch_source_files(): + for file_name in os.listdir(SOURCE_PATH): + _, ext = os.path.splitext(file_name) + if ext == ".rst": + (SOURCE_PATH / file_name).touch() + break + + +def _chmod_output(build_path: Path, apply_func: Callable[[int], int]) -> None: + if not build_path.exists(): + return + + for root, _dirs, files in os.walk(build_path): + for file_name in files: + _, ext = os.path.splitext(file_name) + if ext == ".md": + p = Path(root, file_name) + p.chmod(apply_func(p.stat().st_mode)) + + +def run_sphinx_singlemarkdown(build_path: Path = BUILD_PATH, *flags: str): + """Runs sphinx with singlemarkdown builder and validates success""" + ret_code = main(["-M", "singlemarkdown", str(SOURCE_PATH), str(build_path), "-t", "Partners", *flags]) + assert ret_code == 0 + + +def _singlemarkdown_output_file(build_path: Path) -> Path: + return build_path / "singlemarkdown" / "index.md" + + +def _assert_singlemarkdown_output_exists(build_path: Path) -> Path: + output_file = _singlemarkdown_output_file(build_path) + assert output_file.exists(), f"Output file {output_file} was not created" + return output_file + + +def _assert_singlemarkdown_output_nonempty(build_path: Path) -> str: + output_file = _assert_singlemarkdown_output_exists(build_path) + content = output_file.read_text(encoding="utf-8") + assert content, "Output file is empty" + return content + + +def _assert_matches_expected(actual: str, expected_path: Path) -> None: + expected = expected_path.read_text(encoding="utf-8") + if actual == expected: + return + + diff = "\n".join( + unified_diff( + expected.splitlines(), + actual.splitlines(), + fromfile=str(expected_path), + tofile="generated singlemarkdown output", + lineterm="", + ) + ) + raise AssertionError(f"singlemarkdown output mismatch:\n{diff}") + + +def _make_builder( + root_doc: str = "index", + html_title: str = "Test Title", + project: str = "Test Project", +) -> tuple[SingleFileMarkdownBuilder, mock.MagicMock, mock.MagicMock]: + app = mock.MagicMock() + env = mock.MagicMock() + app.config.root_doc = root_doc + app.config.html_title = html_title + app.config.project = project + builder = SingleFileMarkdownBuilder(app, env) + builder.env = env + builder.out_suffix = ".md" + return builder, app, env + + +def _write_only_scenarios_project(base: Path) -> tuple[Path, Path]: + src = base / "src" + out = base / "build" + src.mkdir(parents=True, exist_ok=True) + + (src / "conf.py").write_text( + "extensions = ['sphinx_markdown_builder']\n" + "project = 'only-scenarios'\n" + "root_doc = 'index'\n", + encoding="utf-8", + ) + + (src / "index.rst").write_text( + "Only Scenarios\n" + "==============\n\n" + ".. only:: html\n\n" + " HTML_ONLY_TOKEN\n\n" + ".. only:: markdown\n\n" + " MARKDOWN_ONLY_TOKEN\n\n" + ".. only:: singlemarkdown\n\n" + " SINGLEMARKDOWN_ONLY_TOKEN\n\n" + ".. only:: markdown or singlemarkdown\n\n" + " BOTH_MD_AND_SINGLE_TOKEN\n", + encoding="utf-8", + ) + + return src, out + + +def test_singlemarkdown_expected_output(): + """Test full singlemarkdown output against a golden expected file.""" + _clean_build_path() + run_sphinx_singlemarkdown(BUILD_PATH, "-a") + + actual = _assert_singlemarkdown_output_nonempty(BUILD_PATH) + _assert_matches_expected(actual, EXPECTED_SINGLE_PATH) + + +def test_singlemarkdown_update(): + """Test rebuilding after changes""" + _touch_source_files() + run_sphinx_singlemarkdown() + _assert_singlemarkdown_output_exists(BUILD_PATH) + + +# Integration tests based on test_builder.py patterns +@pytest.mark.parametrize(["flags", "build_path"], OPTIONS, ids=TEST_NAMES) +def test_singlemarkdown_make_all(flags: Iterable[str], build_path: Path): + """Test building with -a flag (build all)""" + run_sphinx_singlemarkdown(build_path, "-a", *flags) + _ = _assert_singlemarkdown_output_nonempty(build_path) + + +@pytest.mark.parametrize(["flags", "build_path"], OPTIONS, ids=TEST_NAMES) +def test_singlemarkdown_make_updated(flags: Iterable[str], build_path: Path): + """Test rebuilding after changes with different configuration options""" + _touch_source_files() + run_sphinx_singlemarkdown(build_path, *flags) + _assert_singlemarkdown_output_exists(build_path) + + +@pytest.mark.parametrize(["flags", "build_path"], OPTIONS, ids=TEST_NAMES) +def test_singlemarkdown_make_missing(flags: Iterable[str], build_path: Path): + """Test building when the build directory is missing""" + if os.path.exists(build_path): + shutil.rmtree(build_path) + + run_sphinx_singlemarkdown(build_path, *flags) + _assert_singlemarkdown_output_exists(build_path) + + +@pytest.mark.parametrize(["flags", "build_path"], OPTIONS, ids=TEST_NAMES) +def test_singlemarkdown_access_issue(flags: Iterable[str], build_path: Path): + """Test building when files have permission issues""" + _touch_source_files() + flag = stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH + _chmod_output(build_path, lambda mode: mode & ~flag) + try: + run_sphinx_singlemarkdown(build_path, *flags) + finally: + _chmod_output(build_path, lambda mode: mode | flag) + + +def test_singlemarkdown_builder_methods(tmp_path): + """Test SingleFileMarkdownBuilder methods directly""" + # Create a mock app + app = mock.MagicMock() + app.srcdir = "src" + app.confdir = "conf" + app.outdir = "out" + app.doctreedir = str(tmp_path / "doctree") + app.config.root_doc = "index" + + # Create a mock environment + env = mock.MagicMock(spec=BuildEnvironment) + env.all_docs = {"index": None, "page1": None, "target": None} + env.found_docs = {"index", "page1", "target"} + env.toc_secnumbers = {"doc1": {"id1": (1, 2)}} + env.toc_fignumbers = {"doc1": {"figure": {"id1": (1, 2)}}} + + # Create the builder + builder = SingleFileMarkdownBuilder(app, env) + builder.out_suffix = ".md" + + # Test basic methods + assert builder.get_outdated_docs() == "all documents" + assert builder.get_target_uri("index") == "#index" + assert builder.get_target_uri("external") == "external.md" + assert builder.get_relative_uri("source", "target") == "#target" + + +def test_write_uses_base_builder_pipeline(tmp_path): + """Singlemarkdown should rely on Builder.write() and delegate to write_documents().""" + app = mock.MagicMock() + app.doctreedir = str(tmp_path / "doctree") + env = mock.MagicMock(spec=BuildEnvironment) + app.config.root_doc = "index" + env.found_docs = {"index", "other"} + env.files_to_rebuild = {} + env.toctree_includes = {} + + builder = SingleFileMarkdownBuilder(app, env) + builder.prepare_writing = mock.MagicMock() + builder.copy_assets = mock.MagicMock() + builder.write_documents = mock.MagicMock() + + builder.write(build_docnames={"other"}, updated_docnames=[], method="all") + + builder.prepare_writing.assert_called_once_with({"other"}) + builder.copy_assets.assert_called_once() + builder.write_documents.assert_called_once() + called_docnames = builder.write_documents.call_args.args[0] + assert called_docnames == {"other"} + assert "other" in called_docnames + + +def test_write_serial_uses_single_file_generation_path(tmp_path): + """Legacy _write_serial hook should generate the merged singlemarkdown output.""" + app = mock.MagicMock() + app.doctreedir = str(tmp_path / "doctree") + env = mock.MagicMock(spec=BuildEnvironment) + + builder = SingleFileMarkdownBuilder(app, env) + builder._write_single_markdown = mock.MagicMock() + + builder._write_serial(["index", "other"]) + + builder._write_single_markdown.assert_called_once() + + +def test_write_parallel_uses_single_file_generation_path(tmp_path): + """Legacy _write_parallel hook should generate one merged output file.""" + app = mock.MagicMock() + app.doctreedir = str(tmp_path / "doctree") + env = mock.MagicMock(spec=BuildEnvironment) + + builder = SingleFileMarkdownBuilder(app, env) + builder._write_single_markdown = mock.MagicMock() + + builder._write_parallel(["index", "other"], 2) + + builder._write_single_markdown.assert_called_once() + + +def test_render_partial(tmp_path, monkeypatch): + """Test render_partial method""" + monkeypatch.chdir(tmp_path) + builder, _, _ = _make_builder() + + # Test with None node + result = builder.render_partial(None) + assert result["fragment"] == "" + + with mock.patch("sphinx_markdown_builder.singlemarkdown.MarkdownWriter") as mock_writer_class: + mock_writer = mock.MagicMock() + mock_writer.output = "Test content output" + mock_writer_class.return_value = mock_writer + + # Reset builder.writer + builder.writer = None + + # Test document node + doc = mock.MagicMock(spec=nodes.document) + + # The method will create a new writer + result = builder.render_partial(doc) + + # Check that a new writer was created and used + assert mock_writer_class.called + + # Since we're completely mocking things, just verify the call was made + # rather than checking specific output + assert isinstance(result, dict) + assert "fragment" in result + + +def test_render_partial_non_document_node(tmp_path, monkeypatch): + """Test render_partial with a non-document node.""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder() + env.settings = mock.MagicMock() + + with mock.patch("sphinx_markdown_builder.singlemarkdown.MarkdownWriter") as mock_writer_class: + mock_writer = mock.MagicMock() + mock_writer.output = None + mock_writer_class.return_value = mock_writer + + paragraph = nodes.paragraph("", "Partial content") + result = builder.render_partial(paragraph) + + assert isinstance(result, dict) + assert result["fragment"] == "" + assert mock_writer.write.called + + +def test_get_local_toctree(tmp_path, monkeypatch): + """Test _get_local_toctree method""" + monkeypatch.chdir(tmp_path) + builder, _, _ = _make_builder() + + # Mock render_partial to avoid issues with document settings + with mock.patch.object(builder, "render_partial") as mock_render: + mock_render.return_value = {"fragment": "mock toctree content"} + + # Mock the global_toctree_for_doc function + with mock.patch("sphinx_markdown_builder.singlemarkdown.global_toctree_for_doc") as mock_toctree: + # Create a toc node for testing + toc = nodes.bullet_list() + item = nodes.list_item() + item += nodes.paragraph("", "Test item") + toc.append(item) + mock_toctree.return_value = toc + + # Test with normal parameters + result = builder._get_local_toctree("index") + assert result == "mock toctree content" + + # Test with includehidden as string + result = builder._get_local_toctree("index", includehidden="true") + assert mock_toctree.call_args[1]["includehidden"] is True + + result = builder._get_local_toctree("index", includehidden="false") + assert mock_toctree.call_args[1]["includehidden"] is False + + # Test with empty maxdepth + result = builder._get_local_toctree("index", maxdepth="") + assert "maxdepth" not in mock_toctree.call_args[1] + + +def test_assemble_doctree(tmp_path, monkeypatch): + """Test assemble_doctree method.""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder() + + tree = _new_test_document() + env.get_doctree.return_value = tree + + with mock.patch("sphinx_markdown_builder.singlemarkdown.inline_all_toctrees", return_value=tree) as mock_inline: + result = builder.assemble_doctree() + + assert result is tree + assert result["docname"] == "index" + mock_inline.assert_called_once() + env.resolve_references.assert_called_once_with(tree, "index", builder) + + +def test_assemble_toc_secnumbers(tmp_path, monkeypatch): + """Test assemble_toc_secnumbers method""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder() + + # Set up environment data + env.toc_secnumbers = {"doc1": {"id1": (1, 2)}, "doc2": {"id2": (3, 4)}} + + # Run the method + result = builder.assemble_toc_secnumbers() + + # Check result + assert "index" in result + assert "doc1/id1" in result["index"] + assert "doc2/id2" in result["index"] + assert result["index"]["doc1/id1"] == (1, 2) + assert result["index"]["doc2/id2"] == (3, 4) + + +def test_assemble_toc_fignumbers(tmp_path, monkeypatch): + """Test assemble_toc_fignumbers method""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder() + + # Set up environment data + env.toc_fignumbers = { + "doc1": {"figure": {"id1": (1, 2)}}, + "doc2": {"table": {"id2": (3, 4)}}, + } + + # Run the method + result = builder.assemble_toc_fignumbers() + + # Check result + assert "index" in result + assert "doc1/figure" in result["index"] + assert "doc2/table" in result["index"] + assert "id1" in result["index"]["doc1/figure"] + assert "id2" in result["index"]["doc2/table"] + assert result["index"]["doc1/figure"]["id1"] == (1, 2) + assert result["index"]["doc2/table"]["id2"] == (3, 4) + + +def test_get_doc_context(tmp_path, monkeypatch): + """Test get_doc_context method""" + monkeypatch.chdir(tmp_path) + builder, _, _ = _make_builder() + + # Test with toctree + with mock.patch("sphinx_markdown_builder.singlemarkdown.global_toctree_for_doc") as mock_toctree: + toc_node = nodes.bullet_list() + toc_node += nodes.list_item("", nodes.reference("", "Test link", internal=True)) + mock_toctree.return_value = toc_node + + with mock.patch.object(builder, "render_partial", return_value={"fragment": "toc content"}): + result = builder.get_doc_context("index", "Test body", "Test metatags") + + assert result["body"] == "Test body" + assert result["metatags"] == "Test metatags" + assert result["display_toc"] is True + assert result["toc"] == "toc content" + + # Test without toctree + with mock.patch("sphinx_markdown_builder.singlemarkdown.global_toctree_for_doc") as mock_toctree: + mock_toctree.return_value = None + + result = builder.get_doc_context("index", "Test body", "Test metatags") + + assert result["body"] == "Test body" + assert result["metatags"] == "Test metatags" + assert result["display_toc"] is False + assert result["toc"] == "" + + +def test_write_documents(tmp_path, monkeypatch): + """Test write_documents method with mocks""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder() + _configure_write_documents_builder(builder, env, {"index": None, "page1": None}, {"index", "page1"}) + + # Create a test document + doc_index = _new_test_document() + doc_index.append(nodes.paragraph("", "Test index content")) + + doc_page1 = _new_test_document() + doc_page1.append(nodes.paragraph("", "Test page1 content")) + + # Mock get_doctree to return our test documents + env.get_doctree.side_effect = lambda docname: doc_index if docname == "index" else doc_page1 + + _run_write_documents(builder) + + # Verify output file was created + expected_file = os.path.join(BUILD_PATH, "index.md") + + # Clean up + if os.path.exists(expected_file): + os.remove(expected_file) + + +def test_write_documents_uses_toctree_order(tmp_path, monkeypatch): + """Single markdown output should follow depth-first toctree order.""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder(project="Order Test") + _configure_write_documents_builder( + builder, + env, + { + "index": None, + "z-last": None, + "a-first": None, + "mid": None, + "orphan": None, + }, + {"index", "z-last", "a-first", "mid", "orphan"}, + ) + + env.toctree_includes = { + "index": ["mid", "a-first"], + "mid": ["z-last"], + } + + seen_docnames: list[str] = [] + + def get_doc(docname: str) -> nodes.document: + seen_docnames.append(docname) + return _new_test_document() + + env.get_doctree.side_effect = get_doc + + _run_write_documents(builder) + + assert seen_docnames == ["index", "mid", "z-last", "a-first"] + + +def test_write_documents_error_handling(tmp_path, monkeypatch): + """Test error handling in write_documents""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder() + _configure_write_documents_builder(builder, env, {"index": None, "page1": None}, {"index", "page1"}) + + # Setup to raise exception when getting doctree for "page1" + def mock_get_doctree(docname: str): + if docname == "page1": + raise Exception("Test exception") + return _new_test_document() + + env.get_doctree.side_effect = mock_get_doctree + + _run_write_documents(builder) + + +def test_write_documents_os_error(tmp_path, monkeypatch): + """Test OS error handling in write_documents""" + monkeypatch.chdir(tmp_path) + builder, _, env = _make_builder() + _configure_write_documents_builder(builder, env, {"index": None}, {"index"}) + + # Create a test document + doc = _new_test_document() + doc.append(nodes.paragraph("", "Test content")) + env.get_doctree.return_value = doc + + _run_write_documents(builder, OSError("Test error")) + + +def test_setup_registers_extension(): + """Test setup function metadata and extension registration.""" + app = mock.MagicMock() + + metadata = setup(app) + + app.setup_extension.assert_called_once_with("sphinx_markdown_builder") + assert metadata["version"] == "builtin" + assert metadata["parallel_read_safe"] is True + assert metadata["parallel_write_safe"] is True diff --git a/tests/test_unit.py b/tests/test_unit.py index 257996c..bea35f8 100644 --- a/tests/test_unit.py +++ b/tests/test_unit.py @@ -6,6 +6,7 @@ import docutils.nodes import pytest +from sphinx import addnodes import sphinx.util.logging from sphinx_markdown_builder.contexts import SubContext @@ -16,6 +17,7 @@ def make_mock(): document = Mock(name="document") document.settings.language_code = "en" builder = Mock(name="builder") + builder.heading_level_offset = 0 return MarkdownTranslator(document, builder) @@ -75,3 +77,78 @@ def test_problematic(): mt.dispatch_visit(node) mt.add("suffix") assert mt.astext() == "prefix\n\n```\ntext\n```\n\nsuffix\n" + + +def test_desc_optional_is_wrapped_in_brackets(): + mt = make_mock() + node = addnodes.desc_optional() + + mt.visit_desc_optional(node) + mt.add("timeout") + mt.depart_desc_optional(node) + + assert "[timeout]" in mt.astext() + + +def test_desc_parameter_without_parameterlist_does_not_fail(): + mt = make_mock() + node = addnodes.desc_parameter() + + mt.add("prefix ") + mt.visit_desc_parameter(node) + mt.add("value") + mt.depart_desc_parameter(node) + + assert "prefix value" in mt.astext() + + +def test_desc_parameter_inside_optional_uses_nearest_sep_context(): + mt = make_mock() + parameterlist = addnodes.desc_parameterlist() + optional = addnodes.desc_optional() + first = addnodes.desc_parameter() + second = addnodes.desc_parameter() + + mt.visit_desc_parameterlist(parameterlist) + mt.visit_desc_optional(optional) + + mt.visit_desc_parameter(first) + mt.add("timeout") + mt.depart_desc_parameter(first) + + mt.depart_desc_optional(optional) + + mt.visit_desc_parameter(second) + mt.add("retries") + mt.depart_desc_parameter(second) + + mt.depart_desc_parameterlist(parameterlist) + + assert "[timeout], retries" in mt.astext() + + +def test_caution_is_rendered_as_admonition(): + mt = make_mock() + node = docutils.nodes.caution() + + mt.visit_caution(node) + mt.add("Handle with care") + mt.depart_caution(node) + + output = mt.astext() + assert "CAUTION" in output + assert "Handle with care" in output + + +def test_highlightlang_sets_default_code_language(): + mt = make_mock() + node = addnodes.highlightlang(lang="python", force=False, linenothreshold=0) + code = docutils.nodes.literal_block("", "") + code["classes"] = [] + + mt.visit_highlightlang(node) + mt.visit_literal_block(code) + mt.add("print('ok')") + mt.depart_literal_block(code) + + assert "```python" in mt.astext()