Hello! First, swift-doc looks like it could be a really useful tool so thank you!

I attempted to run swift-doc with a project I am working on that relies on MapboxGeocoder and I ran into a weird scenario where swift-doc returns an error of

Error: Error Domain=NSCocoaErrorDomain Code=257 "The file “MapboxGeocoder.swift” couldn’t be opened because you don’t have permission to view it."

The problem seems to be that MapboxGeocoder, when installed via Cocoapods, creates a directory in /Pods named MapboxGeocoder.swift which swift-doc then tries to read as a Swift source file because it looks like a Swift source file if you just look at the name. Removing MapboxGeocoder from the project I am working on though and then running swift-doc works as expected!

I don't know how common of a problem this is, figured I would at least pass it along as something that I ran into when getting started with trying out swift-doc.

As an author of the frameworks which work on multiple platforms and have slightly different APIs for each one, I would like to be able to generate different sets of documentation for each platform and allow users to select which one they want to see.

As an alternative, it could be the same documentation, but it should clearly indicate which APIs are available on which platforms.

GitHub renders shortcodes like :heart_eyes :.

This causes issues for code symbols like this initializer:

• Unescaped: init(imports:symbols:)
• Escaped in code: init(imports:symbols:)

One of the consequences of #65 is that we now have an option that applies to HTML output, but not CommonMark. This kind of divergence isn't unexpected — certainly, as we expand functionality to support additional output formats like DocSets (#27), it was inevitable.

We're at the point now where the original assumptions we made to ship the initial proof-of-concept are starting to break down, and it'd be great to find a solution that will set us up for success in version 1.x and beyond.

Here's what I'm looking for in a solution, in order of importance:

1. Something that lets us add support for new formats, without encroaching on or breaking the existing ones.
2. The ability to test generated output without actually running the swift-doc command (a full integration test should be run separately), as discussed in #62
3. The ability for users to use a 3rd-party generator without forking swift-doc itself — for extensibility, but also some flexibility for us about what's included in the main offering.

...so basically, a plugin system. 😭

So far, the only solution I've been able to come up with that meets all three of these criteria is to make each format its own subcommand of generate. For example, running:

$ swift doc generate html

...would look for an executable named swift-doc-generate-html. This is the same approach that allows swift-doc to be executed as a subcommand of swift, and would let anyone write and/or install their own custom output format.

Does anyone else have any other ideas about what we should do?

Package Resources offer a way to load CSS and JavaScript from the module bundle (as opposed to our current approach of hard-coding CSS in a string literal).

Although it looks like the "Package Manager Extensible Build Tools" proposal is no longer being considered, I think we should be able to leverage webpack (or any of its myriad colleagues) to generate resources on an as-needed basis.

As seen in #50, the symbol next to the Resolver shows as C for class instead of T for typealias.

Hi, I deployed the documentation generated by swift-doc to GitHub pages. There is an issue with path-relative URLs. For example, if you got to ImageProcessing page and click of any of the URLs there, e.g. ImageProcessors.Resize, it shows 404 page.

I'm using the latest swift-doc from master:

commit 0b2291a52f22a30d5e2528f06be79d40cac570cb (HEAD -> master, origin/master, origin/HEAD)
Merge: e5c4b85 0ac5744
Author: Mattt <[email protected]>
Date:   Sun Apr 5 08:15:44 2020 -0700

    Merge pull request #53 from SwiftDocOrg/mattt/operator-fix
    
    Fix logic error when classifying operators in generate subcommand

The Service Worker API allows webpages to download, install, and activate resources that can later be used by the browser. This allows users to view webpages when they're not connected to the Internet or the server hosting the original webpage is offline. Typically, things like cache invalidation and state restoration present significant challenges to adoption, but we fortunately don't have to deal with those for static content like documentation.

For example, a reference to Codable in a code block should link to Apple's documentation.

In the original README, there was a Motivation section that included a list of the project's dependencies, like SwiftSemantics. We should bring back and revise this for the next release.

For example, this code block renders as:

I attempted to use the GitHub Action and it fails to build as it seems it cannot find libxml2. My yaml file is mostly copied from the readme as such:

 name: documentation

 on: 
   push:
     branches:
       - master

 jobs:

   documentation:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v1
       - name: Generate Documentation
         uses: SwiftDocOrg/swift-doc@master
         with:
           inputs: "Source"
           output: "Documentation"
       - name: Upload Documentation to Wiki
         uses: SwiftDocOrg/github-wiki-publish-action@v1
         with:
           path: "Documentation"
         env:
           GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

with the following error:

2020-04-02T10:51:17.1999611Z �[91mwarning: you may be able to install libxml-2.0 using your system-packager:
2020-04-02T10:51:17.1999887Z     apt-get install libxml2-dev
2020-04-02T10:51:17.1999968Z 
2020-04-02T10:51:17.3529060Z �[0m[1/22] Compiling cmark xml.c
2020-04-02T10:51:19.3766648Z [2/23] Compiling cmark utf8.c
2020-04-02T10:51:20.9528071Z [3/24] Compiling HypertextLiteral Swift+HyperTextConvertible.swift
2020-04-02T10:51:39.8014675Z [4/25] Compiling GraphViz Attribute.swift
2020-04-02T10:51:40.1024297Z [5/26] Compiling DOM Comment.swift
2020-04-02T10:51:40.1026381Z <module-includes>:1:10: note: in file included from <module-includes>:1:
2020-04-02T10:51:40.1026549Z #include "libxml2-markup.h"
2020-04-02T10:51:40.1027053Z          ^
2020-04-02T10:51:40.1027215Z /swiftdoc/.build/checkouts/Markup/Modules/libxml2-markup.h:3:9: error: 'libxml2/libxml/tree.h' file not found
2020-04-02T10:51:40.1027441Z #import <libxml2/libxml/tree.h>
2020-04-02T10:51:40.1027583Z         ^
2020-04-02T10:51:40.1027730Z /swiftdoc/.build/checkouts/Markup/Sources/DOM/Comment.swift:1:8: error: could not build C module 'libxml2'
2020-04-02T10:51:40.1027943Z import libxml2
2020-04-02T10:51:40.1028086Z        ^
2020-04-02T10:51:40.1145904Z Makefile:17: recipe for target 'swift-doc' failed
2020-04-02T10:51:40.1146156Z �[91mmake: *** [swift-doc] Error 1
2020-04-02T10:51:40.6684447Z The command '/bin/sh -c make install prefix=/build' returned a non-zero code: 2
2020-04-02T10:51:40.6693539Z �[0m
2020-04-02T10:51:40.6811173Z ##[error]Docker build failed with exit code 2

I have attached the full log of that step of the workflow run: 2_Build [email protected], but as it's an open source project, you can see the results for yourself on the repo.

If there's only one page of documentation, that should replace the Home page (which would otherwise show a list comprising that one symbol)

Here be dragons 🐲

In an effort to get everything out the door, I kind of took a "whatever works" approach to development. To that end, HyperTextLiteral was great for getting out of the way. But it's obvious that we're leaving a lot of performance wins on the table with our current implementation.

Once the design stabilizes, it'd be nice to take another pass over all of this to clean and speed things up.

Sub-Tasks

• Extract repeated markup patterns into components (e.g. definition lists of symbols)
• Create helper functions for things like string parameterization (`"Foo Bar" -> "foo-bar")

I'm trying to feed the Markdown files generated by swift-doc to Jekyll and it is not happy about certain file names.

~> bundle exec jekyll serve
Configuration file: /Users/kean/Develop/kean.github.io/_config.yml
            Source: /Users/kean/Develop/kean.github.io
       Destination: /Users/kean/Develop/kean.github.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
jekyll 3.8.5 | Error:  Invalid scheme format: cancelRequest(for

The name of the file in question is cancelRequest(for/).md. It was produced for a global function.

For example:

Hi!
first off, thanks for this tool, it's really awesome so far!
I have just come across one issue - I am not sure if it is a bug or a known limitation - but if I generate the documentation, it also creates a documentation for private methods (if they appear in public class).
When I looked through the source code, it really does seem that there is filter for types, but not their properties themselves.

For example:
This function is private but it appears in the generated documentation

It would be great if SwiftDoc's generated docs could inherit the inline documentation for protocol implementations and overrides. For example, Alamofire has a SessionDelegate type which implements the various URLSession*Delegate protocol methods we're interested in. In Xcode, those methods inherit the documentation from the protocol itself. For example:

SwiftDoc currently generates only the method declarations.

Just tried running this on Alamofire.

swift doc generate Source --output swiftdoc --format html --module-name Alamofire

(The --module-name requirement isn't documented, so perhaps the docs need to be updated?)

The command generates some HTML but also prints many lines of "Error Domain=NSPOSIXErrorDomain Code=13 "Permission denied" and then prints a final error:

Error: Error Domain=NSCocoaErrorDomain Code=514 "The item couldn’t be saved because the file name “DataResponseSerializerProtocol_DownloadResponseSerializerProtocol_ResponseSerializer_DataPreprocessor_PassthroughPreprocessor_GoogleXSSIPreprocessor_ResponseSerializer_DownloadResponseSerializerProtocol_DataRequest_DownloadRequest_DataRequest_DataResponseSerializer_DownloadRequest_StringResponseSerializer” is invalid." UserInfo={NSFilePath=/Users/user/Desktop/Code/Alamofire/swiftdoc/DataResponseSerializerProtocol_DownloadResponseSerializerProtocol_ResponseSerializer_DataPreprocessor_PassthroughPreprocessor_GoogleXSSIPreprocessor_ResponseSerializer_DownloadResponseSerializerProtocol_DataRequest_DownloadRequest_DataRequest_DataResponseSerializer_DownloadRequest_StringResponseSerializer, NSUnderlyingError=0x7ff552cf9f70 {Error Domain=NSPOSIXErrorDomain Code=63 "File name too long"}}

I know there are a lot of types in the file, but that's a heck of a file name. 😆

As described in this NSHipster article.

Related to #37

As we begin to add (#65) and consider (#57, #72) new options for the generate command, I think it's likely that the number of options for the generate command will soon exceed what can be reasonably expressed through command-line arguments alone.

Maybe this isn't inevitable. If we took seriously the canon of parsimony in our API design, perhaps we'd find that a small, fixed set of parameters are all that are necessary. This could all be a trap, a slippery slope that projects fall into all too frequently in a rush to add functionality. I'd love to be hear better arguments about limiting feature creep.

But from where I am right now, it's hard to look at, say, the configuration options for jazzy or other comparable tools and think that we'll find a way to solve the same problem without a similar number of settings. Taken altogether in aggregate, you start to get the sense about the inherent complexity of the problem.

So, assuming this is indeed something we'll need, it's probably something we should figure out before 1.0.0. Here's what I'm thinking:

• Extend ArgumentParser to make options Codable. Unless this already exists, this is something that would be useful beyond swift-doc and a good candidate for an upstream patch or separate library.
• By default, look for a .swift-doc.json (spelling?) file and read those as a base configuration, and add an option for where to look for a configuration file.
• Options in the configuration file override the default values. Any options passed from the command line to the executable override ones from a configuration file (similar to how most systems work, including UserDefaults).
• We should also think about versioning and validation for these files, as well as documentation.

Spent the day attempting to add HTML support using [HTMLKit](https://github.com/vapor-community/HTMLKit

Very rudimentary html page created from the top level symbols

fork is: https://github.com/thecb4/swift-doc.git

If you think it's worth it, I can keep going.

<!DOCTYPE html>
<html>
	<head>
		<title>Swift Documentation</title>
		<meta property='og:title' content='Swift Documentation'>
			<meta name='twitter:title' content='Swift Documentation'>
				<meta name='author' content='thebc4'>
					<meta name='twitter:creator' content='_thecb4'>
						<meta name='viewport' content='width=device-width, initial-scale=1.0'>
							<link rel='stylesheet' href='https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css' type='text/css'>
							</head>
							<body>
								<nav class='navbar navbar-light bg-light'>
									<span class='navbar-brand mb-0 h1'>swift-doc</span>
								</nav>
								<div class='p-3'>
									<div class='row'>
										<div class='col-2'>
											<div class='nav flex-column nav-pills' id='v-pills-tab' role='tablist' aria-orientation='vertical'>
												<a class='nav-link active' id='v-pills-Generic-tab' data-toggle='pill' href='#v-pills-Generic' role='tab' aria-controls='v-pills-Generic' aria-selected='false'>Generic</a>
												<a class='nav-link' id='v-pills-Type-tab' data-toggle='pill' href='#v-pills-Type' role='tab' aria-controls='v-pills-Type' aria-selected='false'>Type</a>
												<a class='nav-link' id='v-pills-Contextual-tab' data-toggle='pill' href='#v-pills-Contextual' role='tab' aria-controls='v-pills-Contextual' aria-selected='false'>Contextual</a>
												<a class='nav-link' id='v-pills-SourceFile-tab' data-toggle='pill' href='#v-pills-SourceFile' role='tab' aria-controls='v-pills-SourceFile' aria-selected='false'>SourceFile</a>
												<a class='nav-link' id='v-pills-Unknown-tab' data-toggle='pill' href='#v-pills-Unknown' role='tab' aria-controls='v-pills-Unknown' aria-selected='false'>Unknown</a>
												<a class='nav-link' id='v-pills-Relationship-tab' data-toggle='pill' href='#v-pills-Relationship' role='tab' aria-controls='v-pills-Relationship' aria-selected='false'>Relationship</a>
												<a class='nav-link' id='v-pills-Predicate-tab' data-toggle='pill' href='#v-pills-Predicate' role='tab' aria-controls='v-pills-Predicate' aria-selected='false'>Predicate</a>
												<a class='nav-link' id='v-pills-API-tab' data-toggle='pill' href='#v-pills-API' role='tab' aria-controls='v-pills-API' aria-selected='false'>API</a>
												<a class='nav-link' id='v-pills-CompilationCondition-tab' data-toggle='pill' href='#v-pills-CompilationCondition' role='tab' aria-controls='v-pills-CompilationCondition' aria-selected='false'>CompilationCondition</a>
												<a class='nav-link' id='v-pills-Module-tab' data-toggle='pill' href='#v-pills-Module' role='tab' aria-controls='v-pills-Module' aria-selected='false'>Module</a>
												<a class='nav-link' id='v-pills-Identifier-tab' data-toggle='pill' href='#v-pills-Identifier' role='tab' aria-controls='v-pills-Identifier' aria-selected='false'>Identifier</a>
												<a class='nav-link' id='v-pills-Symbol-tab' data-toggle='pill' href='#v-pills-Symbol' role='tab' aria-controls='v-pills-Symbol' aria-selected='false'>Symbol</a>
												<a class='nav-link' id='v-pills-Component-tab' data-toggle='pill' href='#v-pills-Component' role='tab' aria-controls='v-pills-Component' aria-selected='false'>Component</a>
											</div>
										</div>
										<div class='col-10'>
											<div class='tab-content' id='v-pills-tabContent'>
												<div class='tab-pane fade show active' id='v-pills-Generic' role='tabpanel' aria-labelledby='v-pills-Generic-tab'>
													<h2>Generic</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Type' role='tabpanel' aria-labelledby='v-pills-Type-tab'>
													<h2>Type</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Contextual' role='tabpanel' aria-labelledby='v-pills-Contextual-tab'>
													<h2>Contextual</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-SourceFile' role='tabpanel' aria-labelledby='v-pills-SourceFile-tab'>
													<h2>SourceFile</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Unknown' role='tabpanel' aria-labelledby='v-pills-Unknown-tab'>
													<h2>Unknown</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Relationship' role='tabpanel' aria-labelledby='v-pills-Relationship-tab'>
													<h2>Relationship</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Predicate' role='tabpanel' aria-labelledby='v-pills-Predicate-tab'>
													<h2>Predicate</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-API' role='tabpanel' aria-labelledby='v-pills-API-tab'>
													<h2>API</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-CompilationCondition' role='tabpanel' aria-labelledby='v-pills-CompilationCondition-tab'>
													<h2>CompilationCondition</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Module' role='tabpanel' aria-labelledby='v-pills-Module-tab'>
													<h2>Module</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Identifier' role='tabpanel' aria-labelledby='v-pills-Identifier-tab'>
													<h2>Identifier</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Symbol' role='tabpanel' aria-labelledby='v-pills-Symbol-tab'>
													<h2>Symbol</h2>
												</div>
												<div class='tab-pane fade' id='v-pills-Component' role='tabpanel' aria-labelledby='v-pills-Component-tab'>
													<h2>Component</h2>
												</div>
											</div>
										</div>
									</div>
								</div>
								<footer class='footer fixed-bottom py-4 bg-dark text-white-50'>
									<div class='container text-center'>
										<small>Copyright &copy; swift-doc</small>
									</div>
								</footer>
								<script src='https://code.jquery.com/jquery-3.4.1.slim.min.js'></script>
								<script src='https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/popper.min.js'></script>
								<script src='https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js'></script>
							</body>
						</html>

Right now, swift-doc does a syntactic parse over any source files globbed from the input argument. With #31, it'll be much easier to sort things out and understand how symbols relate to one another.

If a public type is named Home, _Sidebar, or _Footer, its generated documentation would be overwritten by the special page of the same name. We should add logic in the generate subcommand to handle this possibility.

My original motivation for swift-doc was to generate documentation for libraries. However, as the tool gains wider adoption, teams will likely want to use it internally for their own apps. The major difference between libraries and apps is that apps are typically much less concerned about ACL (if all of your code is in a single app target, everything "just works").

Rather than force teams to change their code in a way that would otherwise provide no immediate benefit (i.e. sprinkling public throughout their code base), I think it would make sense to provide an option for internal declarations to be included in the generated output.

As far as how this should work:

• The current behavior of only looking for public or open declarations should probably continue to be the default.
• To help folks who might be confused about nothing happening when they run swift doc generate (#70), we should communicate something like "No public declarations found, set the (option) flag to...).
• To accommodate future distinctions, this option should probably take an enumerated value rather than a Boolean. So --minimum-access-level internal instead of --include-internal-declarations.
• And, of course, this should be documented. I think a "Getting Started" guide should be considered a P1 for our 1.0.0 release. (#73)

I just installed swift-doc (for the first time) using

brew install swiftdocorg/formulae/swift-doc

I'm getting the following error when trying to generate any documentation :-

usern:$ swift doc Sources/ --output Documentation
Error: SwiftSyntax parser library isn't compatible
usern:$ 

I've running Catalina 10.15.4 and Xcode 11.4

Thanks!

Hi Mattt, this looks absolutely fantastic and I would really like to start using swift-doc in my projects. I downloaded the latest swift-doc version from master (85b5872) and tried running it against Nuke's master.

swift doc generate ~/Develop/Nuke/Sources/ --output Documentation --format html --module-name Nuke

My command line tools are set to Xcode 11.4.

It seems it got a bit confused. I think it might be because of some of the "namespaces" and typealiases.

The actual types are named ImageProcessors.GaussianBlur, etc.

Documentation.zip

As reported in this issue for github-wiki-publish-action, the swift-doc GitHub Action differs from the swift-doc executable in that only one source argument can be passed as an input. This forum thread provides more context and a few suggested workarounds.

While we're waiting for the final command-line interface to be defined, we should update action.yml to reflect this limitation.

As suggested by @MaxDesiatov in #57:

It would be great if there was an option not just to include README.md, but a given directory hierarchy of multiple markdown files that provide extended documentation: tutorials, guidelines, license, code of conduct etc.

Scoping the feature request a bit, I think a good first step would be to add a new, optional parameter to the generate command to specify a directory of Markdown files (Documentation by default) to be rendered alongside the generated symbol reference docs.

For example, given the following project structure:

.
├── Documentation
│   ├── Advanced-Usage.md
│   ├── FAQ.md
│   └── Getting-Started.md
└── Sources

swift doc generate --format html would produce three "Guide" pages for "Advanced Usage", "FAQ", and "Getting Started".

My only hesitation here is that it gets us into the business of static site generation more generally (a corollary of Zawinski's Law. To that end, I'm unsure on whether to should support any form of YAML front matter...

Edit: Actually, you know what? I'm putting my foot down: No YAML front matter! I know of a better way that doesn't add another dependency or threaten to go down a slippery slope of supporting TOML / JSON / whatever front matter — I randomly came across it in this Hugo issue thread:

@bep: This is just me thinking out loud during Christmas. I kind of like the simplicity of it. The idea is to use SGML Processing Instructions as a way to pass parameters to the new and shiny render hooks in Hugo (images and links).

So instead of this:

---
title: Getting Started
---

Reprehenderit culpa qui enim elit sunt laborum do occaecat nostrud exercitation enim ex...

You do something like this (final spelling TBD):

Reprehenderit culpa qui enim elit sunt laborum do occaecat nostrud exercitation enim ex...

<?swiftdoc title="Getting Started" ?>

Processing Instructions aren't rendered by default, and would be otherwise invisible. And unlike front matter, it can appear anywhere in the document.

If we scope this feature to Markdown files with optional PI for customization, I think that strikes a good balance for a "batteries included" output, with the option to further customize using a dedicated static site generator based on the CommonMark output.

hey, it worked for me and generated this html file which is probably
documentation for some pods and third party libraries and can not find any of my classes (models, view , presenters) , i even searched for some code in the documentation and could not find it in my code

Hi @mattt I'm always hitting this issue ?

How could I help fixing it ?

Error: invalidValue(-nan, Swift.EncodingError.Context(codingPath: [NestedCodingKeys(stringValue: "totals", intValue: nil), CodingKeys(stringValue: "percent", intValue: nil)], debugDescription: "Unable to encode Double.nan directly in JSON. Use JSONEncoder.NonConformingFloatEncodingStrategy.convertToString to specify how the value should be encoded.", underlyingError: nil))
make: *** [doc] Error 1

Thanks,

Most projects provide a helpful overview in their README, and it'd be nice to include that in the generated HTML documentation. This requires a new, optional parameter for the generate command (defaulting to README.md) and additional design work.

Environment

Xcode 11.4

Steps

• Pull the latest swift-doc from master
• Open Package.swift
• Run swift-doc target or unit tests for SwiftDoc library

Observed result

dyld: Library not loaded: @rpath/lib_InternalSwiftSyntaxParser.dylib
Referenced from: /Users/kean/Library/Developer/Xcode/DerivedData/swift-doc-enlnpuwdeszizwbdykidcjodocbk/Build/Products/Debug/swift-doc
Reason: image not found

Related

realm/SwiftLint#3105

Most likely using Lunr and a pre-built JSON index.

The quick-and-dirty way to do this would be to hard-code a top-level version constant, but that would require a manual (and therefore error-prone) process of updating it for every release.

A better solution would be to pull this information from git during the build process (maybe using GYB?).

Even better would be if the Swift Package Manager had a way to generate these symbols at build time. Does anyone know if this is currently possible? And if not, what do you think about requesting this through Swift Evolution?

As mentioned in #39, the README used to have a "Motivation" section that discussed how swift-doc compared to Jazzy. I removed that for the first beta, because a lot of that information was no longer accurate or relevant. But we should definitely provide some similar guidance when this gets closer to a final release.

Requirements do not appear in the HTML output but are present in the markdown version. Please let me know if you want me to open a PR for the fix.

Operators, functions, typealiases appear in Markdown, but not in HTML.

Currently, swift-doc builds a symbol graph syntactically. However, this approach has limitations (#25, #16). We may want to keep the current, syntactic approach around as an option for quick-and-dirty doc generation, but in the long-term, we'll likely want to leverage IndexStoreDB for this.

Steps to reproduce?

• Project: https://github.com/kaishin/Gifu
• How I installed swift-doc: git clone then make install
• Exact command: swift-doc generate ./Sources/ --module-name Gifu --output Documentation --format html

Expected behavior

• HTML documentation generated at ./Documentation
• No error output

Actual behavior

• HTML documentation generated at ./Documentation
• The following output

Error Domain=NSPOSIXErrorDomain Code=13 "Permission denied"
Error Domain=NSPOSIXErrorDomain Code=13 "Permission denied"

Environment

• OS version: 10.15.4 (19E266)

Expanding on what's currently in the README, we should provide a step-by-step tutorial to help onboard new users.

I just tested swift-doc on my package Bluebird: https://github.com/AndrewBarba/Bluebird.swift

The Promise class, declared here, is being generated as State.​State​Handler.​Promise.

State and StateHandler are two internal enums declared above the Promise class in the same file.

Generated docs: https://andrewbarba.github.io/Bluebird.swift/

Installed on macOS 10.15.4 via Homebrew

Xcode 11.4 on macOS 10.15.4

The README instructions for manual installation direct you to clone the swift-doc repo, cd into the folder, and run make install.

When I attempt make install, terminal displays a lot of "Cloning" and "Resolving" messages then a warning:
warning: failed to retrieve search paths with pkg-config; maybe pkg-config is not installed 'libxml2' libxml-2.0.pc: warning: couldn't find pc file

and then continues to work until it ends with this:

[45/45] Linking swift-doc install: chmod 755 /usr/local/bin: Operation not permitted install: /usr/local/bin/swift-doc: Permission denied make: *** [install] Error 71

Hi @mattt any plans for supporting Objective-C files? Would love to use this in a project that I am working on that is mainly written in Objective-C

getting this error after running command "make install"

error: the package dependency graph could not be resolved; possibly because of these requirements: https://github.com/SwiftDocOrg/SwiftSemantics.git @ 0.1.0..<0.2.0 make: *** [swift-doc] Error 1

For Dash, and other clients.

When running the swift-doc GitHub action on Sources/SwiftDoc, the resulting documentation for SourceFile has the name "Contextual.Symbol.Extension.CompilationCondition.SourceFile".

Contextual.Symbol.Extension.CompilationCondition.SourceFile

Running this locally on macOS, I'm unable to reproduce this behavior.

This long name is a consequence of the SourceFile declaration following declarations relating to the Contextual protocol.

This should be handled by visitPost, which pops the stack of contexts after visiting a contextual node:

However, these delegate methods don't appear to be called on Linux for some reason.

As described in this tweet:

Is there a way to continue proceeding/skipping when some file errors. I am getting Domain=NSCocoaErrorDomain Code=514 "The item couldn’t be saved because the file name XYZ is invalid or too long?

This seems to be a result of #25, but we should also recover from these kinds of errors, emitting a warning to the console instead of exiting.

Thanks this looks awesome! I did a quick test and I think I found some bugs.

I created a new Swift package and put the following in the source file:

/// Says hello
public func sayHello() {
    print("Hello!")
}

public extension NSNumber {
    /// Does this number represent a Bool
    public var isBool: Bool { return CFBooleanGetTypeID() == CFGetTypeID(self) }
}

public extension Result where Failure == Error {
    /// Converts a throwing block into a Result
    /// If any error is thrown a failure result is returned with the error. Otherwise success with the blocks return value.
    public static func of(_ block: () throws -> Success) -> Result<Success, Error> {
        do {
            return try .success(block())
        } catch {
            return .failure(error)
        }
    }
}

/**
 The default generated struct!
 */
struct spm_test {
    var text = "Hello, World!"
}

When I run the generator via swift doc generate Sources --module-name spm-test I get the following:

Home.md

# Types

  - [NSNumber.Result.spm\_test](NSNumber_Result_spm_test)

# Operators

  - [sayHello()](sayHello\(\))

NSNumber_Result_spm_test.md

# NSNumber.Result.spm\_test

The default generated struct\!

``` swift
struct spm_test
```

## Properties

## text

``` swift
var text = "Hello, World!"
```

sayHello().md

# sayHello()

## sayHello()

Says hello

``` swift
public func sayHello()
```

I think there are three bugs here:

1. Notice how the spm_test struct is nested under the NSNumber and Result types.
2. I don't get any docs for the public extensions.
3. The top level sayHello function is documented as an operator.