How does SourceDocs compare to Jazzy for Swift documentation?

SourceDocs generates Markdown files for inline repository storage, ideal for version control and GitHub Pages, while Jazzy produces HTML for standalone documentation sites. SourceDocs is better for keeping docs with code, whereas Jazzy suits web publishing with more styling options.

How to generate documentation for only a specific module in SourceDocs?

Use the --spm-module option for Swift packages or --module-name for general modules. For example, run 'sourcedocs generate --spm-module MyModule' from the package root, as detailed in the usage section.

Can SourceDocs document private or internal APIs?

Yes, by using the --min-acl option to set the minimum access control level, such as 'private' or 'internal'. This allows inclusion of non-public members in the generated Markdown documentation.

Is SourceDocs compatible with CI/CD pipelines like GitHub Actions?

Yes, as a command-line tool, it can be integrated into CI/CD scripts. However, since it requires Xcode, you need to ensure the environment has Xcode installed, which might add complexity on non-macOS runners.

How to change the output directory for generated documentation?

Use the -o or --output-folder option to specify a custom path. For instance, 'sourcedocs generate -o Docs/API' will write files to the Docs/API directory instead of the default Documentation/Reference.

Does SourceDocs support documenting SwiftUI code?

SourceDocs parses Swift source code comments, so it should work with SwiftUI. However, it doesn't have special handling for SwiftUI-specific syntax or previews, so standard documentation comments are required for proper generation.

Open-Awesome

SourceDocs

MITSwift2.0.1

A command line tool that generates Markdown documentation from inline Swift source code comments.

GitHub

423 stars45 forks0 contributors

What is SourceDocs?

SourceDocs is a command line tool that generates Markdown documentation files from inline comments in Swift source code. It parses Swift projects and packages to create beautiful reference documentation that can be stored directly in the project repository. It solves the problem of keeping API documentation synchronized with code changes by automating documentation generation.

Target Audience

Swift developers working on Xcode projects or Swift Packages who need to generate and maintain API reference documentation. It's particularly useful for open-source library maintainers and teams wanting browsable inline documentation.

Value Proposition

Developers choose SourceDocs because it generates clean Markdown files that integrate seamlessly with version control and GitHub Pages, unlike heavier documentation systems. It's specifically designed for Swift ecosystems with native support for both Xcode projects and Swift Package Manager.

Overview

Generate Markdown documentation from source code

Use Cases

Best For

Generating API reference documentation for Swift libraries
Creating browsable documentation for Swift Package Manager modules
Maintaining documentation that lives alongside Swift source code
Automating documentation generation in CI/CD pipelines
Producing Markdown documentation renderable on GitHub Pages
Documenting both Xcode projects and Swift packages with a single tool

Not Ideal For

Teams requiring HTML output or interactive documentation browsers like Dash or DevDocs
Projects that need documentation generated on non-macOS platforms such as Linux or Windows
Developers who prefer GUI-based documentation tools over command-line interfaces

Pros & Cons

Pros

Native Swift Ecosystem Support

Seamlessly integrates with both Xcode projects and Swift Package Manager, automatically analyzing public types without manual configuration, as highlighted in the features list.

Version Control Friendly Output

Generates Markdown files that can be stored inline in the repository, making documentation easily browsable on platforms like GitHub Pages, as recommended in the README.

Highly Customizable Generation

Offers options such as collapsible blocks, table of contents, and access level filtering via command-line flags, allowing tailored documentation to suit project needs.

Lightweight and Simple

Produces clean Markdown instead of heavier formats like HTML, reducing complexity compared to tools like Jazzy, as noted in the README comparison.

Cons

Platform-Locked to macOS

Requires Xcode and specific Swift versions, as shown in the Requirements table, limiting its use to Apple ecosystems and hindering cross-platform documentation workflows.

Setup Complexity for Xcode Projects

The README admits that commands may fail with default settings, necessitating manual specification of schemes or arguments, which can be error-prone for some users.

Limited Output Format Support

Only generates Markdown files, lacking built-in support for HTML, PDF, or other formats that might be needed for professional documentation hosting or publishing.

Open Source Alternative To

SourceDocs is an open-source alternative to the following products:

Jazzy

Jazzy is a Ruby spell checker library that uses Aspell or Hunspell dictionaries to provide spelling suggestions and corrections.

Sphinx

Frequently Asked Questions

Related Projects

Swift Argument Parser

Straightforward, type-safe argument parsing for Swift

Compose beautiful command line interfaces in Swift

Stars1,536

Forks84

Last commit4 years ago

Swiftline

Swiftline is a set of tools to help you create command line applications.

Stars1,194

Forks99