Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/SourceDocs/SourceDocs
Generate Markdown documentation from source code
https://github.com/SourceDocs/SourceDocs
command-line-tool documentation documentation-generator documentation-tool executable generator markdown swift
Last synced: 3 months ago
JSON representation
Generate Markdown documentation from source code
- Host: GitHub
- URL: https://github.com/SourceDocs/SourceDocs
- Owner: SourceDocs
- License: mit
- Created: 2017-10-04T23:23:11.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-04-02T18:48:15.000Z (7 months ago)
- Last Synced: 2024-05-23T02:36:41.844Z (6 months ago)
- Topics: command-line-tool, documentation, documentation-generator, documentation-tool, executable, generator, markdown, swift
- Language: Swift
- Homepage:
- Size: 906 KB
- Stars: 380
- Watchers: 5
- Forks: 39
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-ios - SourceDocs - Command Line Tool that generates Markdown documentation from inline source code comments. (Command Line / Linter)
- awesome-swift - SourceDocs - Generate Markdown reference documentation that lives with your code. (Libs / Documentation)
- fucking-awesome-swift - SourceDocs - Generate Markdown reference documentation that lives with your code. (Libs / Documentation)
README
# SourceDocs
[](https://github.com/eneko/SourceDocs/releases)
[](https://travis-ci.org/eneko/SourceDocs)
[](https://codecov.io/gh/eneko/SourceDocs)
[](https://swift.org/package-manager)
[](https://codebeat.co/projects/github-com-eneko-sourcedocs-master)
SourceDocs is a command line tool that generates markdown
documentation files from inline source code comments.
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/`.
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
- [SourceDocsLib](/docs/reference/SourceDocsLib)
- [SourceDocsDemo](/docs/reference/SourceDocsDemo)
- [SourceDocs Package](/docs/Package.md)
- [Apollo iOS API Reference](https://www.apollographql.com/docs/ios/api-reference/)
- [Workflow framework (by Square)](https://square.github.io/workflow/swift/api/Workflow/)
## Requirements
| SourceDocs Version | Xcode Version | Swift Version |
| ------------------ | ------------- | ------------- |
| 2.x | 13.1 | 5.5 |
| 1.x | 11.5 | 5.1 |
## 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
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 ` we get a list of all options for that command:
$ sourcedocs generate --help
OVERVIEW: Generates the Markdown documentation
USAGE: source-docs generate
ARGUMENTS:
List of arguments to pass to xcodebuild
OPTIONS:
-a, --all-modules Generate documentation for all modules in a Swift package
--spm-module
Generate documentation for Swift Package Manager module
--module-name
Generate documentation for a Swift module
--link-beginning
The text to begin links with
--link-ending
The text to end links with (default: .md)
-i, --input-folder
Path to the input directory (default: /Users/ramses.alonso/Development/eneko/SourceDocs)
-o, --output-folder
Output directory to clean (default: Documentation/Reference)
--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
-s, --skip-empty Do not generate documentation for files with no comments.
-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](https://www.twitter.com/eneko).
## Contributions
If you find an issue, just [open a ticket](https://github.com/eneko/SourceDocs/issues/new)
on it. Pull requests are warmly welcome as well.
## License
SourceDocs is licensed under the MIT license. See [LICENSE](/LICENSE) for more info.