Swift DocC is a documentation compiler launched by Apple in Xcode 13, designed to assist builders create elegant and interactive documentation for his or her iOS and macOS tasks. The compiler converts your Markdown-based remark into wealthy documentation. With Swift Docc, you may incorporate code snippets, diagrams, and even interactive tutorials instantly into your documentation, enabling readers to achieve a deeper understanding of your code and the way it works.
The generated documentation is displayed instantly within the Xcode documentation window, giving builders a seamless and built-in expertise. Along with having the ability to show your documentation in Xcode, you can even host it on an internet site. It is a nice method to share your documentation with a wider viewers and make it extra accessible.
On this tutorial, I’ll offer you a fast walkthrough of Swift DocC and present you how you can publish the code documentation onto your personal net web page or share it on GitHub Web page.
Documenting Your Swift Code with DocC
To create documentation utilizing DocC, you’ll want to make use of a customized variant of Markdown referred to as documentation markup. The syntax is much like Markdown however it provides performance for code documentation-specific options corresponding to cross-symbol hyperlink and time period lists. Assuming you’ve got some expertise with Markdown, you must know how you can use documentation markup.
To doc your supply code in Xcode, you may maintain the command key and click on the strategy title.
By selecting the Add Documentation possibility, Xcode will generate a template that features placeholders for all the mandatory parts. You possibly can then write your personal description to supply details about the operate and parameters.
|
/// <#Description#> /// – Parameters: ///Â Â – index: <#index description#> ///Â Â – barWidth: <#barWidth description#> ///Â Â – top: <#top description#> /// – Returns: <#description#> personal func getCircleCoordinate(index: Int, barWidth: Double, top: Double) –> CGPoint { Â Â Â Â Â let tabWidth = barWidth / Double(tabItems.depend) Â Â Â Â Â let x = tabWidth * Double(index) + tabWidth / 2 Â Â Â Â Â return CGPoint(x: x, y: top) } |
On high of the documentation of your Swift recordsdata, DocC lets you create a touchdown web page (or a top-level web page) that gives an outline of your mission and serves as an entry level of your code documentation.
Though DocC can generate a primary touchdown web page for you, it’s at all times really helpful to create your personal entry web page to present your documentation a novel and personalized effect. Xcode makes this straightforward by robotically creating an empty touchdown web page while you add a documentation catalog to your mission.
Beneath is the Markdown file for the touchdown web page of our MotionBar mission. The primary line of the documentation file is the mission title with an H1 heading. Within the content material half, you present an outline about your mission and any further info that helps different perceive your code.
To assist your reader navigate by way of the supply code, you may group your construction and courses into totally different subjects. You begin with the Subjects key phrase, adopted by part names for every group of sophistication/construction.
That is only a fast walkthrough of the way you format your code documentation utilizing documentation markup. If you wish to dive deeper into the markup language, you may seek advice from the official documentation of DocC.
Producing DocC Documentation from Xcode
To observe the remainder of the tutorial, I counsel you to obtain the demo mission SlothCreator developed by Apple. The pattern mission exhibits you how you can make use of DocC to create code documentation and tutorials.
Constructing your documentation is a breeze with Xcode’s built-in capabilities. To take action, merely navigate to the Xcode menu and choose Product > Construct Documentation. Xcode will then convert your Markdown-based feedback right into a superbly designed documentation that appears much like the official Apple API documentation.
If you happen to’re seeking to export your documentation as a doc archive, merely click on the ... button positioned subsequent to SlothCreator and choose Export. It will help you select your required location and save the exported documentation with a .docarchive file extension.
Constructing a DocC Archive Utilizing Command Line
If you happen to want constructing documentation utilizing Terminal, the doc compiler additionally offers the next command to create a doc archive:
|
xcodebuild docbuild –scheme <SCHEME_NAME> –vacation spot <DESTINATION> –derivedDataPath <YOUR_OUTPUT_PATH> |
Let’s use the SlothCreator mission for example. Open Terminal and alter to the SlothCreator listing (for me, I retailer the mission beneath my Downloads folder):
|
cd ~Downloads/SlothCreatorBuildingDocCDocumentationInXcode |
Kind the next command to construct the documentation:
|
xcodebuild docbuild –scheme SlothCreator –vacation spot ‘title=iPhone 14 Professional’ –derivedDataPath ./construct |
The Doc Builder instrument ought to then generate the doc and reserve it beneath the construct folder. You can see a number of subfolders beneath the construct folder. The doc archive is positioned beneath construct/Construct/Merchandise/Debug-iphonesimulator.
If you happen to can’t find the doc archive file, you need to use the discover command to seek for it:
|
discover ./construct –sort d –title ‘*.doccarchive’ |
Changing DocC Archive for Static Internet hosting
When you efficiently find the doc archive, you may zip it and share it instantly together with your staff members through e-mail or AirDrop. They will open the DocC archive utilizing Xcode.
When Xcode exports a documentation archive, it features a single-page net utility throughout the bundle. This net app is designed to render the documentation content material as HTML. Nonetheless, to host the archive on an internet server, you’ll want to change your net server configuration and add some routing guidelines. Here’s a pattern configuration of Apache (i.e. .htaccess) offered by Apple:
|
# Allow customized routing. RewriteEngine On # Route documentation and tutorial pages. RewriteRule ^(documentation|tutorials)/.*$ SlothCreator.doccarchive/index.html [L] # Route recordsdata and knowledge for the documentation archive. # # If the file path doesn‘t exist within the web site’s root ... RewriteCond %{REQUEST_FILENAME} !–f RewriteCond %{REQUEST_FILENAME} !–d # ... route the request to that file path with the documentation archive. RewriteRule .* SlothCreator.doccarchive/$0 [L] |
If you don’t want to edit the server configuration, DocC additionally lets you convert the doc archive for static internet hosting through the use of the next command:
|
$(xcrun —discover docc) course of–archive remodel–for–static–internet hosting <DOCC_ARCHIVE> —output–path <OUTPUT_PATH> |
Through the use of the transform-for-static-hosting possibility, DocC can generate static hyperlinks with out requiring you to arrange customized routing guidelines.
To proceed with our SlothCreator demo, you may convert the doc archive by operating the next command:
|
$(xcrun —discover docc) course of–archive remodel–for–static–internet hosting ./construct/Construct/Merchandise/Debug–iphonesimulator/SlothCreator.doccarchive —output–path ./htmldoc |
If the whole lot runs easily, DocC generates the HTML recordsdata beneath the htmldoc folder. You possibly can copy the recordsdata to your net server and entry the documentation like this:
|
http://<your_domain>/documentation/slothcreator |
For the tutorials, it’s out there right here:
|
http://<your_domain>/tutorials/slothcreator |
By default, DocC assumes you host the recordsdata beneath the foundation / path. If you happen to want to host the documentation beneath a subfolder, you may add the choice hosting-base-path when executing the command above like this:
|
$(xcrun —discover docc) course of–archive remodel–for–static–internet hosting ./construct/Construct/Merchandise/Debug–iphonesimulator/SlothCreator.doccarchive —output–path ./htmldoc —internet hosting–base–path /demo |
We set the bottom path to /demo. On this case, you’ll entry the documentation utilizing the next URL:
|
http://<your_domain>/demo/documentation/slothcreator |
Internet hosting the DocC Documentation on GitHub Pages
To host the documentation on GitHub web page, you first create a brand new repository named username.github.io, the place username is your username (or group title) on GitHub.
Subsequent, clone the brand new repository and retailer in your most well-liked mission folder utilizing the command under:
|
git clone https://github.com/appcoda/appcoda.github.io |
You’ll want to interchange the instance username and repository title with your personal. As soon as your repository is about up, you may then copy the documentation recordsdata that you simply beforehand ready into the mission folder.
For me, since I take advantage of the foundation path as the bottom path, I simply copy your whole DocC recordsdata into the folder named appcoda.github.io.
Now it’s prepared so as to add and add the recordsdata to your distant repository. Key within the following instructions beneath your mission folder:
|
git add —all git commit –m “Preliminary commit” git push –u origin major |
As soon as all recordsdata are uploaded onto GitHub, you must be capable to entry your documentation at https://.github.io/documentation/slothcreator.
Abstract
Internet hosting your Swift DocC documentation on an internet server is a superb method to share your documentation with a wider viewers and make it extra accessible. By following the steps on this tutorial, you may simply create elegant documentation in your iOS and macOS tasks. And yo’ve realized how you can publish it by yourself web site or on GitHub Pages. With DocC, you may incorporate diagrams and even interactive tutorials instantly into your documentation, enabling readers to achieve a deeper understanding of your code and the way it works. So give DocC a attempt to make your documentation extra attention-grabbing!
