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 render with GitHub Pages.

Features

  • ✅ Browse reference documentation within the project repository (great for private projects)
  • ✅ Browse reference documentation on GitHub Pages (great for public projects)

Usage

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

$ cd ~/path/to/MyAppOrFramework
$ sourcedocs generate

This command will analyze your MyAppOrFramework project and generate reference documentation from all public types found. The documentation is written to the directory Documentation/Reference relative to the root of your project repository.

Usage options

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

$ sourcedocs help
Available commands:

clean      Delete the output folder and quit.
generate   Generates the Markdown documentation
help       Display general or command-specific help
version    Display the current version of SourceDocs

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

$ sourcedocs help generate

Generates the Markdown documentation

[--spm-module (string)]
	Generate documentation for Swift Package Manager module.

[--module-name (string)]
	Generate documentation for a Swift module.
	
[--input-folder (string)]
   Input directory (defaults to the current working directory).

[--output-folder (string)]
   Output directory (defaults to Documentation/Reference).
   
[--min-acl (private|fileprivate|internal|public|open)]
   Minimum access level to process the documentation for (defaults to public).

[--link-beginning (string)]
   The string to begin links with. Defaults to an empty string.
   
[--link-ending (string)] 
   The string to end links with. Defaults to `".md"`.

--clean|-c
	Delete output folder before generating documentation.

[[]]
	List of arguments to pass to xcodebuild.

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

For Swift Package Manager modules, you can the module name using the --spm-module parameter.

$ sourcedocs generate --spm-module SourceDocsDemo

Generated documentation

SourceDocs writes documentation files to the Documentation/Reference directory relative to your project root. 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>.

We highly recommend adding the generated documentation to your source code repository, so it can be easily browsed inline. GitHub and BitBucket do a great job rendering Markdown files, so your documentation will be very nice to read.

Example Generated Documentation SourceDocs Example

Installation

Download Binary

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

From Sources

Requirements:

  • Swift 4 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: 198
Help us keep the lights on

Releases

0.6.1 - Nov 3, 2019

Breaking

  • None

Enhancements

  • None

Bug Fixes

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

0.6.0 - Nov 1, 2019

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

0.5.1 - Sep 26, 2018

Breaking

  • None

Enhancements

  • None

Bug Fixes

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

0.5.0 - Nov 14, 2017

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

0.4.0 - Oct 25, 2017

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.