Swiftpack.co - Package - eneko/SourceDocs

SourceDocs

Release Build Status codecov Swift 5.0 Swift Package Manager Compatible codebeat badge

SourceDocs Header

SourceDocs is a command line tool that generates markdown documentation files from inline source code comments.

Terminal Output

Similar to Sphinx or Jazzy, SourceDocs parses your Swift source code and generates beautiful reference documentation. In contrast to those other tools, SourceDocs generates markdown files that you can store and browse inline within your project repository. Or even render with GitHub Pages.

Features

  • ✅ Generate reference documentation from Xcode projects
  • ✅ Generate reference documentation from Swift Packages
  • ✅ Generate package description documentation from Swift Packages

Generated documentation

SourceDocs writes documentation files to the Documentation/Reference directory relative to your project root (path can be configured). This allows for the generated documentation to live along other hand-crafted documentation you might have written or will write in the future.

When specifying a module name, the documentation files will be written to Documentation/Reference/<module name>.

It's recommended adding this generated documentation to the source code repository, so it can be easily browsed inline. GitHub, BitBucket and other source control platforms do a great job rendering Markdown files, so documentation is easy to read.

Examples of Generated Documentation

Usage

Swift Packages

To generate documentation for a Swift Package, run sourcedocs from the root of your package repository.

$ cd path/to/MyPackage
$ sourcedocs generate --all-modules

This command will generate documentation for each module in your Swift package.

For a specific module, pass the module name using the --spm-module parameter.

$ sourcedocs generate --spm-module SourceDocsDemo

Xcode Projects

To generate documentation from your source code, run sourcedocs directly from the root your Xcode project.

$ cd path/to/MyAppOrFramework
$ sourcedocs generate

This command will analyze your Xcode project and generate reference documentation from all public types found.

Usually, for most Xcode projects, no parameters are needed at all. xcodebuild should be able to find the default project and scheme.

If the command fails, try specifying the scheme (-scheme SchemeName) or the workspace. Any arguments passed to sourcedocs after -- will be passed to xcodebuild without modification.

$ sourcedocs generate -- -scheme MyScheme

Usage options

Typing sourcedocs help we get a list of all available commands:

$ sourcedocs help
USAGE: source-docs <subcommand>

OPTIONS:
  -h, --help              Show help information.

SUBCOMMANDS:
  clean                   Delete the output folder and quit.
  generate                Generates the Markdown documentation
  package                 Generate PACKAGE.md from Swift package description.
  version                 Display the current version of SourceDocs

Typing sourcedocs help <command> we get a list of all options for that command:

$ sourcedocs generate --help

OVERVIEW: Generates the Markdown documentation

USAGE: source-docs generate <options>

ARGUMENTS:
  <xcode-arguments>       List of arguments to pass to xcodebuild 

OPTIONS:
  -a, --all-modules       Generate documentation for all modules in a Swift package 
  --spm-module <spm-module>
                          Generate documentation for Swift Package Manager module 
  --module-name <module-name>
                          Generate documentation for a Swift module 
  --link-beginning <link-beginning>
                          The text to begin links with 
  --link-ending <link-ending>
                          The text to end links with (default: .md)
  -i, --input-folder <input-folder>
                          Path to the input directory (default: /Users/ramses.alonso/Development/eneko/SourceDocs)
  -o, --output-folder <output-folder>
                          Output directory to clean (default: Documentation/Reference)
  --min-acl <min-acl>     Access level to include in documentation [private, fileprivate, internal, public, open] (default: public)
  -m, --module-name-path  Include the module name as part of the output folder path 
  -c, --clean             Delete output folder before generating documentation 
  -l, --collapsible       Put methods, properties and enum cases inside collapsible blocks 
  -t, --table-of-contents Generate a table of contents with properties and methods for each type 
  -r, --reproducible-docs Generate documentation that is reproducible: only depends on the sources.
                          For example, this will avoid adding timestamps on the generated files. 
  -h, --help              Show help information

Installation

Download Binary

$ curl -Ls https://github.com/eneko/SourceDocs/releases/latest/download/sourcedocs.macos.zip -o /tmp/sourcedocs.macos.zip
$ unzip -j -d /usr/local/bin /tmp/sourcedocs.macos.zip 

From Sources

Requirements:

  • Swift 5.1 runtime and Xcode installed in your computer.

Using Homebrew

$ brew install sourcedocs

Building with Swift Package Manager

$ git clone https://github.com/eneko/SourceDocs.git
$ cd SourceDocs
$ make

Contact

Follow and contact me on Twitter at @eneko.

Contributions

If you find an issue, just open a ticket on it. Pull requests are warmly welcome as well.

License

SourceDocs is licensed under the MIT license. See LICENSE for more info.

Github

link
Stars: 246

Used By

Total: 0

Releases

Release 1.2.1 - 2020-07-31 20:15:56

Bug Fixes

  • Prepare release 1.2.1 (#62)

Release 1.2.0 - 2020-06-04 15:32:06

Enhancements

  • Add --no-clusters flag to toggle clusters on/off (#55)

Other

  • Remove blockquote from docummentation summary

Release 1.1.0 - 2020-05-27 04:28:01

Breaking

  • None

Enhancements

  • New --all-modules parameter to generate documentation for all swift modules in a package (#49)
  • New --reproducible-docs parameter to generate reproducible documentation (#51)

Bug Fixes

  • Fix issue #50, where nested types where documented out of their parent context (#51)

Release 1.0.0 - 2020-05-11 04:12:17

Breaking

  • Add SourceDocsLib so it can be used by other Swift tools to generate documentation.
  • SourceDocs now requires Swift 5.1 or higher

Enhancements

  • New package command to analyze and document Swift packages.
  • Migrated from Commandant to Swift Argument Parser for command line parsing.

Bug Fixes

  • Fix issue #43 preventing GitHub Pages from being generated

Release 0.6.1 - 2019-11-03 21:28:52

Breaking

  • None

Enhancements

  • None

Bug Fixes

  • Fix --min-acl parameter (#33)

Release 0.6.0 - 2019-11-01 04:34:04

Breaking

  • SourceDocs now requires Swift 5.0 or higher

Enhancements

  • Add ability to pass in link ending text as a parameter (#20)
  • Add ability to specify input folder (#20)
  • Add customizable file beginning (#20)
  • Add --min-acl to let users determine the minimum access level to generate the documentation (#28)

Bug Fixes

  • None

Release 0.5.1 - 2018-09-26 21:56:27

Breaking

  • None

Enhancements

  • None

Bug Fixes

  • Fix: Cannot be installed via Homebrew on Mojave (#10)

Release 0.5.0 - 2017-11-14 04:21:22

Breaking

  • None

Enhancements

  • Enable collapsible blocks for a cleaner output with --collapsible.
  • Enable table of contents for each type with --table-of-contents.

Bug Fixes

  • None

Release 0.4.0 - 2017-10-25 16:09:46

Breaking

  • Updated command line argument handling:
    • Use sourcedocs generate <options> to generate documentation.
    • Use sourcedocs clean <options> to delete the output folder.
    • Use sourcedocs help <command> for more help.
  • Update default output directory to Documentation/Reference

Enhancements

  • Customize output folder with --output-folder.
  • Clean output before generating documentation with --clean.
  • Terminal output is now routed through stdout/stderr.
  • Removed "Declaration" title to reduce noise.
  • New flag --module-name-path to explicitly include module name in output path.

Bug Fixes

  • Documentation links now work both on Markdown and rendered GitHub Pages.

Release 0.3.0 - 2017-10-09 22:52:01

Breaking

  • None

Enhancements

  • Use MarkdownGenerator framework to generate Markdown output.
  • Remove inferred type from output to reduce noise.
  • Add contents table for structs, classes and enums.
  • Comment output is now block-quoted for better formatting.
  • Green checkmarks when writing Markdown files to disk.
  • Remove <sub> HTML tags for a cleaner Markdown output.
  • Remove horizontal guides to reduce noise.

Bug Fixes

  • None

Release 0.2.0 - 2017-10-06 20:37:32

Breaking

  • Update output directory to Docs/Reference to follow Swift Package Manager naming conventions for the project folder structure.

Enhancements

  • Add --clean option to remove Reference Docs folder
  • Add --version option to display current version
  • Update --help command
  • Add Makefile for easier manual build and installation

Bug Fixes

  • None

Release 0.1.0 - 2017-10-06 20:37:10

Initial release