Notes from today's meeting:
Documentation Workgroup Meeting - 10 Feb 2024
hackmd notes: Documentation Workgroup Meeting - 10 Feb 2024 - HackMD
Attendees:
- Vera Mitchell
- Dave Verwer
- Chris McGee
- Rauhul Varma
- Sven Schmidt
- Sofia Rodriguez Morales
- Franklin Schrans
- David Ronnqvist
- Kyle Ye
Topics:
-
(Joe) GSOC (2025) projects ([GSoC 2025] Call for project ideas!)
-
(Rauhul) Plugin added to Swift Argument Parser for generating markdown docs. Chris McGee and Rauhul
are wondering if docs workgroup had ideas on how to generate nicer pages or docc improvements to support this style of docs.reference details from Chris (in Slack):
I'm not sure if this is helpful, but I would love to have the built-in support for UI elements that would allow us to do like they've done with this Sphinx plugin for argparse based Python CLI's: Examples - sphinx-argparse 0.5.2 documentation
I know that we're dealing with Markdown instead of ReST, but DocC does have its own special tags, so maybe we can encode the semantics a bit more than just markup and the HTML generator can use that for some nice presentation.
Here's how Sphinx looks when it documents its own command-line tool: sphinx-build — Sphinx documentation
Discussion
GSOC
(Franklin) GSOC projects
(Sofia) I did the quick-nav GSOC a couple years ago. Does this need to be something in one of the swift projects, or built from scratch?
(Franklin) could be either. GSoC project could be purely experimental that provides interesting learning, never merged.
(Franklin) Documentation Coverage?
(David) There's some stuff to explore there, and reasonably understood open questions - could go in multiple directions (presentation of information, for example)
(Sofia) I might also be interested in mentoring one of the projects. Is there an archive of prior GSoC entries?
(Joe) Konrad's msg on the forums had a lot of links for previous.
(David) (to vera) Is there space for something within symbolgraphs and concurrency, tasks, or macros?
(Vera) The task of adding a new symbol kind is cross-cutting, but very small - getting data from the compiler. Stichting it from there is a "week, not a summer"
(David) Experiment with onboarding any language to SymbolGraph file format and documenting it.
(Sofia) Was thinking along those lines - specifically OpenAPI to SymbolGraph translation.
(Vera) That would be a huge cross-cutting project, could be very interesting.
(Franklin) Sizes in docs are 90, 120, 300 hours (S, M, L)
(David) Will draft up something on Documentation Coverage for GSoC.
(Sofia) last year included Localization support and another.
(Rauhul) would be nice if you could merge graphs from multiple builds.
(Vera) API for this exists in SymbolGraphKit, but there's no corresponding on-disk representation.
(Rauhul) Is this something would be a good project?
(Franklin) The mixed-together builds is pending on multi-platform builds from SwiftPM, then coordinate the graphs from there.
(Rauhul) Annotating APIs with what version they were introduced - would be nice to be able to dig through this and display version diffs for Semantic versions.
(Vera) there's kind of something for this, it's a bit awkward. There's an available directive on DocC. You'd have to write a documentation extension file that allowed you to hand-annotate the availability data with arbitrary platform and version strings, ferried through to the page.
(Rauhul) Would love to tie this back into source generation. Would be nice to be able to display this data at external sites (such as SPI)
(Vera) Being able to hook into an extensible @available attribute would be nice, then we could have this data directly available in the symbolgraph details.
(Kyle) example from Vera's directive:
Example about Vera's available part:
// xx.md
@Metadata {
@Available(Xcode, introduced: 999.0)
@Available(Swift, introduced: 999.0)
}
Styling Markdown for Argument Parser Docs
(Rauhul) Chris wrote a markdown generator plugin that generates markdown for CLI arguments. I shamelessly grabbed this work and upstreamed it into Swift Argument Parser.
(Rauhul) shows existing output. I heard term lists mentioned in the Slack forum thread.
(David) There's a lot you can do there with the syntax at many levels. If this idea is that commands saved on the same page, you can still style each section separately.
(Chris) Here's a more complex example: https://swiftpackageindex.com/swiftlang/swiftly/0.4.0-dev/documentation/swiftlydocs/swiftly-cli-reference
(David) starting with Term lists adds some light hierarchy since it indents, makes it easier to parse in sections.
(David) in the JSON, each flag is a list, but within each flag there's a group name so you could re-generate the top-level grouping for options, etc.
(Rauhul) is there a good way to arrange that in the DocC content
(David) What I'd lean on doing it arranging each into a section.
(David) If we want a page-per-command, there's something you can do - I looked into making a mini-graph for each command, allowing you to give it a custom page type and custom page symbol, providing some different styling. The usage text can also go higher on the page. A symbol also has 3 separate names - top of page, navigation hierarchy, and one that appears in links to the content. That would allow us to display page title only displays name, but when defining an organization, you could display more detail - such as the flags or groups.
(Chris) If we divide the commands into different pages, can we have first class support for cross-linking?
(David) DocC link syntax would work - doesn't matter if symbol or article. You can have more hierarchy for symbols, if you want. With just a sparse command entry into a symbol graph, you get a lot of additional, automatic behavior.
(Chris) I wanted to be able to reference down into a sub-command option, that sort of thing.
(David) What we'd need it including all the command names in the symbolgraph file (representing that hierarchy), and we'd probably want to override how that's displayed to display the flags on the page for the command. (Default would have a page for each symbol)
(Vera) There is some support for symbols that have their own entry, but don't get a page themselves.
(Chris) its probably fine to have one page per command, but larger commands might want to divide things up even further. I hope that one day we could get SwiftPM into something like this, and there's a LOT of subcommands there, which might need this.
(Sofia) This lets us generate swift argument parser commands?
(Rauhul) Right now in main, there's tooling that will read throught the code and dump out markdown with the content loosely generated.
(Rauhul) Could you use metadata directive and not need to use a symbolgraph?
(David) yes, definitely - the symbolgraph would enable it to be a bit more automatic.
(David) where I tend to draw the link is for icons - easy to add an icon to the renderer, but a lot harder to include the raw PNG/SVG in their docc catalog.
(Rauhul) Maybe we could upstream pieces as we need, and generalize it a bit more later.
(Chris) Sphinx defines domains to tooling that allows you to extension in pieces. You can either hand-write documentation using those domain structures, but you can also generate (generators) that use the domain to assemble content.
(Vera) I think you actually could use SymbolGraph as a dependency, it's small and well contained.
SymbolKit doesn't have version tags right now, tagging with a minor on each release branch, but beyond it's just a standalone library.
(Rauhul) is it actually semantically versioned?
(Vera) Not many changes into this structure. SymbolKit is a very slow moving library, haven't had much change that would break the semantic versioning constraints.
(Rauhul) for the short term, adopting term lists in styling would be good. Would love for any of the folks here to help generate and contribute.
(Rauhul) one thing the generator doesn't handle right now, is default values, valid values.
(David) exploratory PR we started Document the supported arguments, flags, and options for DocC's CLI by d-ronnqvist · Pull Request #837 · swiftlang/swift-docc · GitHub
Includes screen shots to see grouping, command line CLI/icon, based on a mix of symbolgraph and markdown. Parsed the JSON output and created a symbolgraph from that. Did the symbols, relationships, and usage at the top. The rest is all markup in the example in the PR.
(Sofia) Do we have a UI element that lets us collapse page sections? I can see this page getting extremely long and complex.
(Franklin) Closest thing is maybe a tab navigator, but that has a different intent.
(Rauhul) I think I see a number of places for incremental adoption. I'll open a few issues to help get something in place.
(David) I'll add up some detail to add this as a GSoC option.
Action Items
- (Joe) send Sofia a copy of Konrad's msg on forums (re: GSoC) with links.
- (Sofia) write up GSoC project based on some previous options
- (David) write up GSoC project offering from Arg-parser translation discussion
- (Rauhul) Add in issues to help bolster the rendering of Swift Arg Parser CLI options.