Skip to content

Update the usage of docc #865

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ktoso merged 2 commits into from
Dec 12, 2021
Merged

Update the usage of docc #865

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6aa20d6
Remove docc and docc render build
Kyle-Ye Dec 11, 2021
6054b54
Update README.md to reflect docc change
Kyle-Ye Dec 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 3 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,13 +105,13 @@ As such, it is necessary to download and use nightly built toolchains to develop

Distributed actors require "latest" nightly toolchains to build correctly.

At this point in time, the **2021-10-26 nightly toolchain** is sufficient to build the project.
At this point in time, the **2021-11-02 nightly toolchain** is sufficient to build the project.
You can download it from [https://swift.org/download/](https://swift.org/download/).

```
# Export the toolchain (nightly snapshot or pull-request generated toolchain), e.g.:

export TOOLCHAIN=/Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-2021-10-26-a.xctoolchain
export TOOLCHAIN=/Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-2021-11-02-a.xctoolchain

# Just build the project
$TOOLCHAIN/usr/bin/swift build --build-tests
Expand Down Expand Up @@ -272,19 +272,14 @@ Only an initial version of API documentation is available right now. This is mos
library is expected to change intensely, along with the evolving language proposal on which this library depends.

You can build API documentation by running the Swift DocC compiler. The [recently released DocC compiler](https://swift.org/blog/swift-docc/) is an official part of the Swift
project, however it is so new, that it does not ship with official toolchains yet. Therefore, we provide scripts that
automate the building and previewing documentation for you. Those will not be necessary once DocC begins to ship with
toolchains.
project, and it ships with the recent nightly toolchains.

Do build documentation run:

```bash
./scripts/docs/generate_docc.sh
```

Upon first invocation, this will download and build the `docc` tool. Subsequent invocations will be fast, as only the
initial call has to download and build the tool itself.

And to preview and browse the documentation as a web-page, run:

```bash
Expand Down
39 changes: 2 additions & 37 deletions scripts/docs/generate_docc.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,48 +35,13 @@ modules=(
DistributedActors
)

declare -r SWIFT="$TOOLCHAIN/usr/bin/swift"

# all our public modules which we want to document, begin with `DistributedActors`
Copy link
Copy Markdown
Contributor Author

@Kyle-Ye Kyle-Ye Dec 11, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This a duplication to the above line

Copy link
Copy Markdown
Contributor Author

@Kyle-Ye Kyle-Ye Dec 11, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add "DistributedActorsTestKit" to sync with the "modules" definition in preview_docc.sh

Copy link
Copy Markdown
Member

@ktoso ktoso Dec 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think you're right -- we want to document the testkit too 👍

modules=(
DistributedActors
)

declare -r build_path=".build/"
declare -r build_path_linux="$build_path/"
declare -r docc_source_path="$root_path/.build/swift-docc"
declare -r docc_render_source_path="$root_path/.build/swift-docc-render"

# Prepare and build docc
if [[ ! -d "$docc_source_path" ]]; then
git clone https://github.com/apple/swift-docc.git "$docc_source_path"
cd $docc_source_path

if [[ ! -d "$docc_source_path/$build_path" ]]; then
swift build -c release
fi
else
echo "Assuming docc is built..."
fi


if [[ ! -d "$docc_render_source_path" ]]; then
git clone https://github.com/apple/swift-docc-render.git "$docc_render_source_path"
cd $docc_render_source_path

npm install
npm run build
else
echo "Assuming docc-render is built..."
fi

export DOCC_HTML_DIR=$docc_render_source_path/dist

# Build documentation

cd $root_path
mkdir -p $root_path/.build/symbol-graphs

declare -r SWIFT="$TOOLCHAIN/usr/bin/swift"

for module in "${modules[@]}"; do
echo "Building symbol-graph for module [$module]..."
$SWIFT build --target $module \
Expand Down
9 changes: 3 additions & 6 deletions scripts/docs/preview_docc.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,10 @@ modules=(
DistributedActorsTestKit
)

declare -r build_path_linux=".build/x86_64-unknown-linux-gnu"
declare -r docc_source_path="$root_path/.build/swift-docc"
declare -r docc_render_source_path="$root_path/.build/swift-docc-render"
declare -r SWIFT_DOCC="$TOOLCHAIN/usr/bin/docc"
export DOCC_HTML_DIR="$TOOLCHAIN/usr/share/docc/render"

export DOCC_HTML_DIR="$docc_render_source_path/dist"

./.build/swift-docc/.build/release/docc preview $root_path/Docs/DistributedActors.docc \
$SWIFT_DOCC preview $root_path/Docs/DistributedActors.docc \
--fallback-display-name DistributedActors \
--fallback-bundle-identifier org.swift.preview.DistributedActors \
--fallback-bundle-version "$version" \
Expand Down