### Untitled No description -------------------------------- ### Installing Sphinx Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Installs the Sphinx documentation generator, which is a Python package built on top of docutils. This command uses pip for installation. ```python python -m pip install sphinx ``` -------------------------------- ### Install and Use Sphinx for Project Documentation (Bash) Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Installs the Sphinx documentation generator and outlines the steps to create a new Sphinx project, build HTML websites, single-page HTML, ePubs, man pages, LaTeX, and plain text outputs. ```bash # Install Sphinx python -m pip install sphinx # Create a new Sphinx project sphinx-quickstart docs # This creates a docs/ directory with: # - index.rst (main document) # - conf.py (configuration) # - Makefile (build script) # - make.bat (Windows build script) # Build documentation to various formats cd docs make html # Build HTML website make singlehtml # Build single-page HTML make epub # Build ePub ebook make man # Build man page make latex # Build LaTeX source make text # Build plain text # The output will be in docs/_build/ ``` -------------------------------- ### Installing Pandoc on macOS Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Installs Pandoc, a universal document converter, on macOS using the Homebrew package manager. This is a common method for managing software on macOS. ```shell brew install pandoc ``` -------------------------------- ### Install docutils using pip Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst This command installs the 'docutils' Python package, which provides the core parser and writer tools for converting reStructuredText documents to various formats. ```bash python -m pip install docutils ``` -------------------------------- ### Untitled No description -------------------------------- ### Starting a New Sphinx Project Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Initializes a new Sphinx documentation project. This command generates a project structure, including an index file, Makefiles, and build directories, prompting for project details. ```shell sphinx-quickstart docs ``` -------------------------------- ### Install and Use Pandoc for Document Conversion (Bash) Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Provides installation guidance for Pandoc, a universal document converter, and demonstrates converting RST files to HTML, DOCX, PDF, and EPUB, as well as converting from Markdown and DOCX to RST. ```bash # Installation varies by platform: # Windows: Download installer from https://github.com/jgm/pandoc/releases # Mac: brew install pandoc # Linux: Download .tar.gz or .deb from GitHub releases # Convert RST to various formats pandoc input.rst -o output.html pandoc input.rst -o output.docx pandoc input.rst -o output.pdf pandoc input.rst -o output.epub # Convert from other formats to RST pandoc input.md -o output.rst pandoc input.docx -o output.rst ``` -------------------------------- ### Python: Minimal Custom Directive Example Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst A simplified Python example showcasing the essential steps for creating a custom reStructuredText directive: defining a class that inherits from Directive and registering it using the directives.register function. ```python class MyCustomDirective(Directive) run(): print('it ran!') return(my custom node? a text node? a code bloc node? an image? etc) process without outputting anything? directives.register('shortcutname', MyCustomDirective) ``` -------------------------------- ### Install and Use docutils for RST Conversion (Bash) Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Installs the docutils Python package and demonstrates converting RST files to HTML5, HTML4, man pages, XML, and LaTeX formats using command-line tools. ```bash # Install docutils using pip python -m pip install docutils # Convert RST to HTML5 rst2html5 mydoc.rst > mydoc.html # Convert to other formats rst2html4 mydoc.rst > mydoc.html rst2man mydoc.rst > mydoc.1 rst2xml mydoc.rst > mydoc.xml rst2latex mydoc.rst > mydoc.tex ``` -------------------------------- ### reStructuredText 'toctree' directive example Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst This is an example of the 'toctree' directive in reStructuredText, commonly used to create a master landing page that links to sub-documents. It's often found in Python's documentation structure. ```rst .. toctree:: whatsnew/index.rst tutorial/index.rst faq/index.rst glossary.rst about.rst bugs.rst copyright.rst license.rst ``` -------------------------------- ### Untitled No description -------------------------------- ### reStructuredText: Tables Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Provides an example of creating tables in reStructuredText using grid table syntax. This involves using pipes and hyphens to define columns and rows, with '=' for header separators and '+' for intersections. ```rst +--------+--------+--------+ | Time | Number | Value | +========+========+========+ | 12:00 | 42 | 2 | +--------+--------+--------+ | 23:00 | 23 | 4 | +--------+--------+--------+ ``` -------------------------------- ### Sublime Text - RST Snippets Plugin Installation and Usage Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Instructions for installing and utilizing the 'Restructured Text (RST) Snippets' plugin in Sublime Text. This plugin enhances the editing experience with features like auto-formatting, smart lists, and navigation. ```text Installation: 1. Install Package Control if not already installed 2. Press Ctrl-Shift-P 3. Type "Package Control: Install Package" 4. Search for "Restructured Text (RST) Snippets" 5. Select and install Key Features: - Auto over/underline formatting: Type 3 chars for header underline, press Tab to expand - Smart bullet lists: Press Enter to auto-continue bullet points - Tab to indent and change bullet character - Quick build/preview: Ctrl-Shift-R to build and preview - Section folding: Shift-Tab on a heading to collapse/expand - Jump between headers: Alt-Up/Down to navigate headings Example workflow: 1. Type heading text: "My Section" 2. Type === below it (just 3 chars) 3. Press Tab - it expands to match title length: My Section ========== 4. Start bullet list with "- Item 1" 5. Press Enter - automatically adds "- " for next item 6. Press Tab - indents and changes to next level bullet (*) ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Minimal Custom HTML Writer using Python and docutils Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Provides a Python example of creating a custom HTML writer by extending docutils' HTML5 polyglot writer. This allows for customized output format and styling by defining a custom translator class. ```python """Minimal writer/translator for customizing docutils output""" from docutils.writers import html5_polyglot from docutils.core import publish_string class MyCustomHTMLTranslator(html5_polyglot.HTMLTranslator): pass class MyCustomHTMLWriter(html5_polyglot.Writer): def __init__(self): html5_polyglot.Writer.__init__(self) self.translator_class = MyCustomHTMLTranslator if __name__ == '__main__': rst_content = """ ================= My Document Title ================= This is a paragraph with *emphasis* and **strong** text. Section ======= Some content here. """ html_output = publish_string( source=rst_content, writer=MyCustomHTMLWriter() ) print(html_output.decode('utf-8')) ``` -------------------------------- ### Minimal custom HTML writer in Python Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst This Python code demonstrates how to create a minimal custom HTML writer and translator by subclassing the 'html5_polyglot' writer from the 'docutils' package. It serves as a starting point for further modifications to the HTML output. ```python """Minimal writer/translator for customizing docutils output""" from docutils.writers import html5_polyglot from docutils.core import publish_string class MyCustomHTMLTranslator(html5_polyglot.HTMLTranslator): pass class MyCustomHTMLWriter(html5_polyglot.Writer): def __init__( self ): html5_polyglot.Writer.__init__(self) self.translator_class = MyCustomHTMLTranslator if __name__ == '__main__': html_output = publish_string(source='Put reStructured text here.', writer=MyCustomHTMLWriter()) print(html_output) ``` -------------------------------- ### Building a Sphinx Project Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Commands to build a Sphinx documentation project into various output formats. The 'make' command is used for building, with specific targets for different formats like HTML, EPUB, and PDF. ```shell make html make singlehtml make epub make man make latex make text ``` -------------------------------- ### Command Line: Building reStructuredText to HTML Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Shows the command-line usage for converting a reStructuredText file (sample.rst) into an HTML file (sample.html) using the 'rst2html5' tool. ```bash rst2html5 sample.rst > sample.html ``` -------------------------------- ### Untitled No description -------------------------------- ### Basic reStructuredText to HTML Conversion Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Demonstrates how to use docutils command-line tools to convert RST files to HTML. The output is directed to stdout and can be piped to a file. ```shell rst2html5 mydoc.rst > mydoc.html ``` -------------------------------- ### Untitled No description -------------------------------- ### reStructuredText: Preserving Line Breaks Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Demonstrates how to preserve line breaks within a paragraph in reStructuredText. Unlike normal text flow, lines starting with a '|' character will render exactly as entered, maintaining the original line breaks. ```rst Normally you can break the line in the middle of a paragraph and it will ignore the newline. If you want to preserve the newlines, use the ``|`` prefix on the lines. For example: | These lines will | break exactly | where we told them to. ``` -------------------------------- ### Untitled No description -------------------------------- ### Displaying Preformatted Text in reStructuredText Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt RST allows for preformatted text blocks that preserve whitespace and formatting. These blocks are typically used for displaying code or text that requires exact rendering. A double colon at the end of a directive starts the preformatted block. ```rst A code example prefix must always end with double colon like it's presenting something:: Anything indented is part of the preformatted block Until It gets back to Allll the way left Now we're out of the preformatted block. ``` -------------------------------- ### Untitled No description -------------------------------- ### reStructuredText: Footnotes and Transitions Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Explains how to create footnotes using reference labels (e.g., '[1]_') or auto-numbered references ('[#]'). It also demonstrates how to create horizontal rules or transitions by using four or more repeated characters on a line, surrounded by blank lines. ```rst Footnote Reference [1]_ .. [1] This is footnote number one that would go at the bottom of the document. Or autonumbered [#] .. [#] This automatically becomes second, based on the 1 already existing. ----------------- Lines/Transitions ----------------- Any 4+ repeated characters with blank lines surrounding it becomes an hr line, like this. ==================================== ``` -------------------------------- ### Untitled No description -------------------------------- ### reStructuredText: Comments and Directives Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Illustrates how to include comments in reStructuredText, which are ignored during rendering but can be output as HTML comments. It also shows the basic syntax for directives like 'image' and custom substitutions. ```rst .. This is a comment Special notes that are not shown but might come out as HTML comments ------ Images ------ Add an image with: .. image:: screenshots/file.png :height: 100 :width: 200 :alt: alternate text You can inline an image or other directive with the |customsub| command. .. |customsub| image:: image/image.png :alt: (missing image text) ``` -------------------------------- ### Creating Grid Tables in reStructuredText Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Demonstrates how to create grid tables using ASCII-art style syntax in reStructuredText. These tables allow for explicit control over cell structure and borders. ```rst +--------+--------+--------+ | Time | Number | Value | +========+========+========+ | 12:00 | 42 | 2 | +--------+--------+--------+ | 23:00 | 23 | 4 | +--------+--------+--------+ +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | Row 1 | Data | More data | | Cell 1 | | | +------------+------------+-----------+ | Row 2 | Data | More data | +------------+------------+-----------+ ``` -------------------------------- ### Untitled No description -------------------------------- ### Basic reStructuredText Document Structure (RST) Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Demonstrates the fundamental structure of an RST document, including a main title, subtitle, primary section headings, and subheadings, along with bulleted lists. ```rst ================= My Project Readme ================= ------------------------- Clever subtitle goes here ------------------------- Introduction ============ This is an example reStructuredText document that starts at the very top with a title and a sub-title. There is one primary header, Introduction. There is one example subheading below. The document is just plain text so it is easily readable even before being converted to HTML, man page, PDF or other formats. Subheading ---------- The basic syntax is not that different from Markdown, but it also has many more powerful features that Markdown doesn't have. We aren't taking advantage of those yet though. - Bullet points - Are intuitive - And simple too ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### reStructuredText: Basic Document Structure and Headings Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Demonstrates the structure of a reStructuredText document, including title, subtitle, and different levels of headings using overline/underline characters. It also shows the use of the 'contents' directive for generating a table of contents. ```rst """""""""""""""""" Document Title """""""""""""""""" ........... Subtitle ........... .. contents:: Overview :depth: 3 =================== Section 1 =================== Text can be *italicized* or **bolded** as well as ``monospaced``. You can \*escape certain\* special characters. ---------------------- Subsection 1 (Level 2) ---------------------- Some section 2 text Sub-subsection 1 (level 3) -------------------------- Some more text. ========= Examples ========= ``` -------------------------------- ### reStructuredText: Links (Autolink, Inline, Labeled) Source: https://github.com/fahreddinozcan/restructuredtext-documentation-reference/blob/master/README.rst Covers various methods for creating links in reStructuredText. This includes automatic linking of URLs, inline custom links with explicit text, and labeled links where the link target is defined separately using a reference name. ```rst Web addresses by themselves will auto link, like this: https://www.devdungeon.com You can also inline custom links: `Google search engine `_ This is a simple link_ to Google with the link defined separately. .. _link: https://www.google.com This is a link to the `Python website`_. .. _Python website: http://www.python.org/ This is a link back to `Section 1`_. You can link based off of the heading name within a document. ``` -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Untitled No description -------------------------------- ### Linking Multiple Documents with toctree in Sphinx Source: https://context7.com/fahreddinozcan/restructuredtext-documentation-reference/llms.txt Demonstrates how to structure large documentation projects in Sphinx by linking multiple documents together using the `.. toctree::` directive in a master document (e.g., `index.rst`). It allows for hierarchical organization and navigation. ```rst In your index.rst: .. toctree:: :maxdepth: 2 :caption: Contents: whatsnew/index.rst tutorial/index.rst faq/index.rst glossary.rst about.rst bugs.rst copyright.rst license.rst # Each referenced file can have its own toctree directive # for nested documentation hierarchies ``` -------------------------------- ### Untitled No description