Skip to content

Commit 99bea04

Browse files
authored
Update distribution documentation static environment enhancements (#587)
* Update distribution docs with static hosting and hosting base path info * Update copyright year in documentation article
1 parent 7774523 commit 99bea04

File tree

1 file changed

+40
-1
lines changed

1 file changed

+40
-1
lines changed

Sources/docc/DocCDocumentation.docc/distributing-documentation-to-other-developers.md

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,45 @@ documentation might resemble the following:
113113
https://www.example.com/documentation/MyNewPackage/MyNewProtocol
114114
```
115115

116+
#### Host a documentation archive with a file server
117+
118+
You can host documentation archives you create with DocC from the Swift 5.7
119+
toolchain and later using a regular file server. By default, the server hosts
120+
the documentation at the root of the website, like the "MyNewPackage" example
121+
above. To host the documentation at a specific subpath, pass a custom hosting
122+
base path for the `--hosting-base-path` option when you build the documentation
123+
archive.
124+
125+
```shell
126+
docc convert MyNewPackage.docc \
127+
--additional-symbol-graph-dir .build \
128+
--output-dir MyNewPackage.doccarchive \
129+
--hosting-base-path MyProject/Base/Path
130+
```
131+
132+
DocC adds the provided hosting base path before the path of each documentation
133+
page. For example, the URL to view for `MyNewProtocol` protocol in the
134+
`MyNewPackage` documentation might resemble the following:
135+
136+
```
137+
https://www.example.com/MyProject/Base/Path/documentation/MyNewPackage/MyNewProtocol
138+
╰────────┬────────╯
139+
your custom base path
140+
```
141+
142+
You can also configure the base path path via the `--hosting-base-path` option
143+
when [building documentation using the SwiftPM DocC Plugin][plugin-docs] or via
144+
the `DOCC_HOSTING_BASE_PATH` build setting when building documentation in Xcode.
145+
146+
[plugin-docs]: https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online/
147+
148+
#### Host a documentation archive using custom routing
149+
150+
A file server is the recommended solution to host your documentation. But, if
151+
you need more control over how the server hosts your content, you can configure
152+
the request routing of your web server so it responds to documentation requests
153+
with the data and assets within the documentation archive.
154+
116155
> Note: The following sections use Apache as an example. Other web server
117156
installations have similar mechanisms. Consult your server's documentation
118157
for details about performing similar configurations.
@@ -154,4 +193,4 @@ to date by using a continuous integration workflow that builds the
154193
documentation archive using `docc`, and copies the resulting
155194
`.doccarchive` to your web server.
156195

157-
<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
196+
<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

0 commit comments

Comments
 (0)