swift-rst-docs 1.0__tar.gz

swift_rst_docs-1.0/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+__pycache__
+.mypy_cache
+dist/*

swift_rst_docs-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emma Labbé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swift_rst_docs-1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: swift-rst-docs
+Version: 1.0
+Summary: Generate RST Swift documentation for Sphinx.
+Project-URL: Homepage, https://git.gatit.es/emma/swift-rst-docs
+Project-URL: Repository, https://git.gatit.es/emma/swift-rst-docs.git
+Author-email: Emma Labbé <emma@labbe.me>
+Maintainer-email: Emma Labbé <emma@labbe.me>
+License-Expression: MIT
+Keywords: documentation,rst,sphinx,swift
+Classifier: Programming Language :: Python
+Requires-Python: >=3.8
+Requires-Dist: beautifulsoup4
+Requires-Dist: pygments
+Requires-Dist: types-pygments
+Description-Content-Type: text/markdown
+
+# swift-rst-docs
+
+Python library and cli to generate reStructuredText documentation for Swift projects from [SourceKitten](https://github.com/jpsim/SourceKitten) output files to use with [Sphinx](https://www.sphinx-doc.org).
+
+This tool assumes the Sphinx output type is HTML because it embeds raw HTML and uses links ending with `.html`.
+
+See the [documentation](https://gatit.es/emma/cosas/documentaciones/swift-rst-docs) for API usage and an example of a generated Swift documentation.
+
+## Installation
+
+```bash
+$ pip install swift-rst-docs
+$ brew install sourcekitten
+```
+
+## Usage
+
+You need to generate a JSON file with SourceKitten first.
+To reference symbols in your documentation, place their full name between 4 backticks. For example: ``` ``MyStructure.hello(world:)`` ``` or ``` ``MySwiftLibrary.MyStructure.hello(world:)`` ``` when referencing from another module or the documentation's overview text. This will create a link to the symbol's page.
+
+```bash
+$ sourcekitten doc [--spm] [-- <swift / xcodebuild arguments>] > documentation.json
+```
+
+### Command Line
+
+Run `swift-rst-docs` to generate RST files.
+You can provide multiple JSON paths to generate documentation for multiple modules.
+
+```bash
+$ swift-rst-docs \
+--title MySwiftPackage \
+--output-path swift-docs \
+--documentation-file-path tests/MySwiftPackage/MySwiftLibrary.json \
+--documentation-file-path tests/MySwiftPackage/MyOtherSwiftLibrary.json \
+[...]
+```
+
+This will generate the pages inside the `swift-docs` directory. All the files are placed in the same directory and are named after the unique identifiers ('usr' documentation entry) of the symbols they document.
+
+More options:
+
+```bash
+usage: swift-rst-docs [-h] --documentation-file-path DOCUMENTATION_FILE_PATH --output-path OUTPUT_PATH
+                      --title TITLE [--overview OVERVIEW] [--files FILES] [--symbols SYMBOLS]
+                      [--min-accessibility {public,internal,fileprivate,private,open}]
+
+options:
+  -h, --help            show this help message and exit
+  --documentation-file-path, -d DOCUMENTATION_FILE_PATH
+                        SourceKitten JSON file path.
+  --output-path, -o OUTPUT_PATH
+                        Output directory path.
+  --title, -t TITLE     Index title.
+  --overview, -v OVERVIEW
+                        Overview file path or contents.
+  --files, -f FILES     File names to document. Can be base names or paths relative to any directory in the source
+                        code. Defaults to all.
+  --symbols, -s SYMBOLS
+                        Symbols to document. Defaults to all.
+  --min-accessibility, -a {public,internal,fileprivate,private,open}
+                        Minimum accessibility of symbols to document. Defaults to public.
+```
+
+### API
+
+You can also use the Python API to programatically generate documentation.
+See the [documentation](https://gatit.es/emma/cosas/documentaciones/swift-rst-docs) for more info.
+
+Example:
+
+```python
+from swift_rst_docs import (
+    GenerationContext, fetch_documents, generate_documentation
+)
+from swift_rst_docs.types import Accessibility
+
+context = GenerationContext(
+    index_title="MySwiftPackage",
+    overview="Example Sphinx documentation for a Swift Package with two libraries.",
+    documented_objects=[
+        # Skip MyOtherSwiftLibrary/MyHiddenSymbols.swift
+        #
+        # The paths are relative to anything: 
+        # you can just write the base names but if you do so there is no way disambiguate between modules.
+        "MySwiftLibrary/MySwiftLibrary.swift",
+        "MyOtherSwiftLibrary/MyOtherSwiftLibrary.swift"
+        ],
+        min_accessibility=Accessibility.PUBLIC
+)
+
+# Fetch symbols and writes them to `context`
+for json_path in [
+    "MySwiftPackage/MySwiftLibrary.json",
+    "MySwiftPackage/MyOtherSwiftLibrary.json",
+]:
+    path = os.path.join(OUTPUT_PATH, json_path)
+    fetch_documents(path, context)
+
+# Write pages
+for page in generate_documentation(context):
+    with open(os.path.join(OUTPUT_PATH, page.file_name), "w+") as f:
+        f.write(page.contents)
+```

swift_rst_docs-1.0/README.md

@@ -0,0 +1,104 @@
+# swift-rst-docs
+
+Python library and cli to generate reStructuredText documentation for Swift projects from [SourceKitten](https://github.com/jpsim/SourceKitten) output files to use with [Sphinx](https://www.sphinx-doc.org).
+
+This tool assumes the Sphinx output type is HTML because it embeds raw HTML and uses links ending with `.html`.
+
+See the [documentation](https://gatit.es/emma/cosas/documentaciones/swift-rst-docs) for API usage and an example of a generated Swift documentation.
+
+## Installation
+
+```bash
+$ pip install swift-rst-docs
+$ brew install sourcekitten
+```
+
+## Usage
+
+You need to generate a JSON file with SourceKitten first.
+To reference symbols in your documentation, place their full name between 4 backticks. For example: ``` ``MyStructure.hello(world:)`` ``` or ``` ``MySwiftLibrary.MyStructure.hello(world:)`` ``` when referencing from another module or the documentation's overview text. This will create a link to the symbol's page.
+
+```bash
+$ sourcekitten doc [--spm] [-- <swift / xcodebuild arguments>] > documentation.json
+```
+
+### Command Line
+
+Run `swift-rst-docs` to generate RST files.
+You can provide multiple JSON paths to generate documentation for multiple modules.
+
+```bash
+$ swift-rst-docs \
+--title MySwiftPackage \
+--output-path swift-docs \
+--documentation-file-path tests/MySwiftPackage/MySwiftLibrary.json \
+--documentation-file-path tests/MySwiftPackage/MyOtherSwiftLibrary.json \
+[...]
+```
+
+This will generate the pages inside the `swift-docs` directory. All the files are placed in the same directory and are named after the unique identifiers ('usr' documentation entry) of the symbols they document.
+
+More options:
+
+```bash
+usage: swift-rst-docs [-h] --documentation-file-path DOCUMENTATION_FILE_PATH --output-path OUTPUT_PATH
+                      --title TITLE [--overview OVERVIEW] [--files FILES] [--symbols SYMBOLS]
+                      [--min-accessibility {public,internal,fileprivate,private,open}]
+
+options:
+  -h, --help            show this help message and exit
+  --documentation-file-path, -d DOCUMENTATION_FILE_PATH
+                        SourceKitten JSON file path.
+  --output-path, -o OUTPUT_PATH
+                        Output directory path.
+  --title, -t TITLE     Index title.
+  --overview, -v OVERVIEW
+                        Overview file path or contents.
+  --files, -f FILES     File names to document. Can be base names or paths relative to any directory in the source
+                        code. Defaults to all.
+  --symbols, -s SYMBOLS
+                        Symbols to document. Defaults to all.
+  --min-accessibility, -a {public,internal,fileprivate,private,open}
+                        Minimum accessibility of symbols to document. Defaults to public.
+```
+
+### API
+
+You can also use the Python API to programatically generate documentation.
+See the [documentation](https://gatit.es/emma/cosas/documentaciones/swift-rst-docs) for more info.
+
+Example:
+
+```python
+from swift_rst_docs import (
+    GenerationContext, fetch_documents, generate_documentation
+)
+from swift_rst_docs.types import Accessibility
+
+context = GenerationContext(
+    index_title="MySwiftPackage",
+    overview="Example Sphinx documentation for a Swift Package with two libraries.",
+    documented_objects=[
+        # Skip MyOtherSwiftLibrary/MyHiddenSymbols.swift
+        #
+        # The paths are relative to anything: 
+        # you can just write the base names but if you do so there is no way disambiguate between modules.
+        "MySwiftLibrary/MySwiftLibrary.swift",
+        "MyOtherSwiftLibrary/MyOtherSwiftLibrary.swift"
+        ],
+        min_accessibility=Accessibility.PUBLIC
+)
+
+# Fetch symbols and writes them to `context`
+for json_path in [
+    "MySwiftPackage/MySwiftLibrary.json",
+    "MySwiftPackage/MyOtherSwiftLibrary.json",
+]:
+    path = os.path.join(OUTPUT_PATH, json_path)
+    fetch_documents(path, context)
+
+# Write pages
+for page in generate_documentation(context):
+    with open(os.path.join(OUTPUT_PATH, page.file_name), "w+") as f:
+        f.write(page.contents)
+```

swift_rst_docs-1.0/docs/.gitignore

@@ -0,0 +1 @@
+build/*

swift_rst_docs-1.0/docs/Makefile

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

swift_rst_docs-1.0/docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 714af83a85c4e7cbce835b4a9db4a2eb
+tags: 645f666f9bcd5a90fca523b33c5a78b7

swift_rst_docs-1.0/docs/build/html/_sources/cli.rst.txt

@@ -0,0 +1,41 @@
+CLI Usage
+=========
+
+Run ``swift-rst-docs`` to generate RST files.
+You can provide multiple JSON paths to generate documentation for multiple modules.
+
+.. code-block:: bash
+
+   $ swift-rst-docs \
+   --title MySwiftPackage \
+   --output-path swift-docs \
+   --documentation-file-path tests/MySwiftPackage/MySwiftLibrary.json \
+   --documentation-file-path tests/MySwiftPackage/MyOtherSwiftLibrary.json \
+   [...]
+
+This will generate the pages inside the ``swift-docs`` directory. All the files are placed in the same directory and are named after the unique identifiers (``usr`` documentation entry) of the symbols they document.
+
+More options:
+
+.. code-block:: bash
+
+   usage: swift-rst-docs [-h] --documentation-file-path DOCUMENTATION_FILE_PATH --output-path OUTPUT_PATH
+                         --title TITLE [--overview OVERVIEW] [--files FILES] [--symbols SYMBOLS]
+                         [--min-accessibility {public,internal,fileprivate,private,open}]
+
+   options:
+     -h, --help            show this help message and exit
+     --documentation-file-path, -d DOCUMENTATION_FILE_PATH
+                           SourceKitten JSON file path.
+     --output-path, -o OUTPUT_PATH
+                           Output directory path.
+     --title, -t TITLE     Index title.
+     --overview, -v OVERVIEW
+                           Overview file path or contents.
+     --files, -f FILES     File names to document. Can be base names or paths relative to any directory in the source
+                           code. Defaults to all.
+     --symbols, -s SYMBOLS
+                           Symbols to document. Defaults to all.
+     --min-accessibility, -a {public,internal,fileprivate,private,open}
+                           Minimum accessibility of symbols to document. Defaults to public.
+

swift_rst_docs-1.0/docs/build/html/_sources/index.rst.txt

@@ -0,0 +1,85 @@
+.. swift-rst-docs documentation master file, created by
+   sphinx-quickstart on Wed Apr 15 03:32:14 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+swift-rst-docs
+==============
+
+Python library and CLI to generate reStructuredText documentation for Swift projects from `SourceKitten <https://github.com/jpsim/SourceKitten>`_ output files to use with `Sphinx <https://www.sphinx-doc.org>`_ HTML output.
+
+Document
+--------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   cli
+   reference
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Example Output
+
+   swift/index
+
+
+Installation
+------------
+
+.. code-block:: bash
+
+   $ pip install swift-rst-docs
+
+API Usage
+---------
+
+You need to generate a JSON file with SourceKitten first.
+To reference symbols in your documentation, place their full name between 4 backticks. For example: ````MyStructure.hello(world:)\`\``` or ````MySwiftLibrary.MyStructure.hello(world:)```` when referencing from another module or the documentation's overview text. This will create a link to the symbol's page.
+
+.. code-block:: bash
+
+   $ sourcekitten doc [--spm] [-- <swift / xcodebuild arguments>] > documentation.json
+
+API Example
+-----------
+
+First, create a :py:class:`swift_rst_docs.types.GenerationContext` object and populate it with your options.
+Then call :py:func:`swift_rst_docs.doc.fetch_documents` for each JSON file you want to process.
+And finally, call :py:func:`swift_rst_docs.doc.generate_documentation` to generate and return all the documentation RST files.
+
+.. code-block:: python
+
+   from swift_rst_docs import (
+       GenerationContext, fetch_documents, generate_documentation
+   )
+   from swift_rst_docs.types import Accessibility
+
+   context = GenerationContext(
+       index_title="MySwiftPackage",
+       overview="Example Sphinx documentation for a Swift Package with two libraries.",
+       documented_objects=[
+           # Skip MyOtherSwiftLibrary/MyHiddenSymbols.swift
+           #
+           # The paths are relative to anything:
+           # you can just write the base names but if you do so there is no way disambiguate between modules.
+           "MySwiftLibrary/MySwiftLibrary.swift",
+           "MyOtherSwiftLibrary/MyOtherSwiftLibrary.swift"
+       ],
+       min_accessibility=Accessibility.PUBLIC
+   )
+
+   # Fetch symbols and writes them to `context`
+   for json_path in [
+       "MySwiftPackage/MySwiftLibrary.json",
+       "MySwiftPackage/MyOtherSwiftLibrary.json",
+   ]:
+       path = os.path.join(OUTPUT_PATH, json_path)
+       fetch_documents(path, context)
+
+   # Write pages
+   for page in generate_documentation(context):
+       with open(os.path.join(OUTPUT_PATH, page.file_name), "w+") as f:
+           f.write(page.contents)
+

swift_rst_docs-1.0/docs/build/html/_sources/reference.rst.txt

@@ -0,0 +1,37 @@
+API Reference
+=============
+
+.. automodule:: swift_rst_docs
+
+
+Generation
+----------
+
+.. autofunction:: swift_rst_docs.fetch_documents
+.. autofunction:: swift_rst_docs.generate_documentation
+.. autofunction:: swift_rst_docs.GenerationContext
+.. autofunction:: swift_rst_docs.main
+
+Parsing
+-------
+
+.. autofunction:: swift_rst_docs.parse
+.. autofunction:: swift_rst_docs.fetch_fullnames
+.. autofunction:: swift_rst_docs.replace_links
+.. autofunction:: swift_rst_docs.highlight_statement
+.. autofunction:: swift_rst_docs.prettify_swift_declaration
+
+Types
+-----
+
+.. autoclass:: swift_rst_docs.Accessibility
+.. autoclass:: swift_rst_docs.AnnotatedDeclaration
+.. autoclass:: swift_rst_docs.Annotation
+.. autoclass:: swift_rst_docs.DeclarationKind
+.. autoclass:: swift_rst_docs.Documentation
+.. autoclass:: swift_rst_docs.MARK
+.. autoclass:: swift_rst_docs.MainPage
+.. autoclass:: swift_rst_docs.ModulePage
+.. autoclass:: swift_rst_docs.Page
+.. autoclass:: swift_rst_docs.Structure
+.. autoclass:: swift_rst_docs.Symbol

swift_rst_docs-1.0/docs/build/html/_sources/swift/MyOtherSwiftLibrary.rst.txt

@@ -0,0 +1,33 @@
+MyOtherSwiftLibrary
+===================
+
+
+
+.. raw:: html
+
+   <style>
+   .doc-link {
+       font-family: var(--font-stack--monospace);
+   }
+   </style>
+
+   <script type="text/javascript">
+   window.onload = function() {
+       document.querySelectorAll("a[href*='#doclink']").forEach(function(link) {
+           link.classList.add("doc-link");
+           link.href = link.href.replace("#doclink", "");
+       });
+   }
+   </script>
+
+.. code-block:: swift
+
+    import MyOtherSwiftLibrary
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Functions
+
+   s_19MyOtherSwiftLibrary5Hello6animalSS0acD06AnimalO_tF
+

swift_rst_docs-1.0/docs/build/html/_sources/swift/MySwiftLibrary.rst.txt

@@ -0,0 +1,45 @@
+MySwiftLibrary
+==============
+
+
+
+.. raw:: html
+
+   <style>
+   .doc-link {
+       font-family: var(--font-stack--monospace);
+   }
+   </style>
+
+   <script type="text/javascript">
+   window.onload = function() {
+       document.querySelectorAll("a[href*='#doclink']").forEach(function(link) {
+           link.classList.add("doc-link");
+           link.href = link.href.replace("#doclink", "");
+       });
+   }
+   </script>
+
+.. code-block:: swift
+
+    import MySwiftLibrary
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Structures
+
+   s_14MySwiftLibrary0A9StructureV
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Protocols
+
+   s_14MySwiftLibrary0A8ProtocolP
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Enumerations
+
+   s_14MySwiftLibrary6AnimalO
+

swift_rst_docs-1.0/docs/build/html/_sources/swift/index.rst.txt

@@ -0,0 +1,30 @@
+MySwiftPackage
+==============
+
+Example Sphinx documentation for a Swift Package with two libraries.
+
+
+.. raw:: html
+
+   <style>
+   .doc-link {
+       font-family: var(--font-stack--monospace);
+   }
+   </style>
+
+   <script type="text/javascript">
+   window.onload = function() {
+       document.querySelectorAll("a[href*='#doclink']").forEach(function(link) {
+           link.classList.add("doc-link");
+           link.href = link.href.replace("#doclink", "");
+       });
+   }
+   </script>
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Modules
+
+   MySwiftLibrary
+   MyOtherSwiftLibrary
+

swift_rst_docs-1.0/docs/build/html/_sources/swift/s_14MySwiftLibrary0A8ProtocolP.rst.txt

@@ -0,0 +1,64 @@
+``MyProtocol``
+==============
+
+.. index:: s:14MySwiftLibrary0A8ProtocolP
+
+A protocol.
+
+
+
+.. raw:: html
+
+   <style>
+   .doc-link {
+       font-family: var(--font-stack--monospace);
+   }
+   </style>
+
+   <script type="text/javascript">
+   window.onload = function() {
+       document.querySelectorAll("a[href*='#doclink']").forEach(function(link) {
+           link.classList.add("doc-link");
+           link.href = link.href.replace("#doclink", "");
+       });
+   }
+   </script>
+
+
+
+.. raw:: html
+
+   <style>
+   .toctree-wrapper ul {
+       list-style-type: none;
+       padding-left: 0;
+       margin-left: 0;
+   }
+
+   .toctree-l1 {
+       list-style: none;
+   }
+
+   .main .toctree-l1 > a > code > .pre { font-size: 120% !important; }
+   </style>
+
+Declaration
+-----------
+
+
+.. raw:: html
+
+     <div class="highlight"><pre><span></span><span class="kd">protocol</span><span class="w"> </span><span class="nc">MyProtocol</span>
+   </pre></div>
+
+
+Functions
+---------
+.. toctree::
+   :maxdepth: 1
+
+   s_14MySwiftLibrary0A8ProtocolP3foo3barS2S_tF
+
+Documentation text.
+
+