Comments (5)
This is kind of a good first issue. The coding changes are fairly small but there's a good opportunity here for a developer to think about the tradeoffs between various solutions and have a discussion in the Swift Forums to find the right solution.
Discussing the tradeoffs in the Swift Forums will require a new developer to familiarize themselves with behaviors of docc convert
and docc preview
.
from swift-docc.
Hi @d-ronnqvist, I would like to work on this. Since this issue is quite old, do you now if there's been any work or discussion related to it that I should be aware of?
from swift-docc.
Hi. as far as I’m aware there has been no further work or discussion on this issue.
from swift-docc.
There are a couple of different places where you could check if the build doesn't result in any pages.
The only place that I'm aware of that checks this today is in PreviewAction.printPreviewAddresses(base:)
which prints the base preview paths of all the top-level pages (module pages, technology roots, and tutorials). The preview actions gets these paths from the documentation context as
previewPaths = try convertAction.context.previewPaths()
which in turn checks the context's rootModules
and rootTechnologies
. This works because individual symbols and articles only get a page if they belong to some module or technology.
We wouldn't want to tie this diagnostic to the code that prints the preview addresses but the underlying check could be the same.
One thing to consider is that the preview action internally uses a convert action, so if the two should behave differently then the convert action likely needs some new configuration that the preview action can control.
from swift-docc.
Hi @d-ronnqvist. I agree that this solution could use a combination of the different options you listed. My most immediate proposition when either previewing or converting documentation that will end up with no pages is to raise a warning, and, in the case of docc convert
, not emit a doccarchive for those documentations that resulted in no pages. So a combination of solutions 1 and 2. This can also be discussed on the forums with the rest of the community. I’ll open a discussion there to talk about this.
In the meantime, could you point me to the files inside Swift-DocC that I should keep an eye on for this implementation? My best guess is that I have to check that the topic
dictionary inside renderContext.store
has data in it.
// DocumentationConverter.swift
mutating public func convert<OutputConsumer: ConvertOutputConsumer>(
outputConsumer: OutputConsumer
) throws -> (analysisProblems: [Problem], conversionProblems: [Problem]) {
...
// Precompute the render context
let renderContext = RenderContext(documentationContext: context, bundle: bundle)
// Emit warning if renderContext.store.topics is empty
...
}
from swift-docc.
Related Issues (20)
- Typealiased type are not reflected properly in the documentation HOT 4
- Reenable DefaultDiagnosticConsoleFormatter HOT 1
- Crash when building locally HOT 4
- Duplicated diagnostic causing crash on DefaultDiagnosticConsoleFormatter HOT 8
- Overly strict warning when curating a module under a technology root HOT 19
- Line numbers in code listings HOT 3
- The wrong role is assigned to the technology-root node in article-only catalogs
- Any way to merge the index.json for multiple framework hosting on single Static site ? HOT 8
- Provide `@Embed` directive as an equivalent of HTML <embed/> or <iframe/>
- Swift-DocC should display C++ and Objective-C++ as their own source languages
- Sitemap for DocC Hosted Website HOT 6
- source link line number mismatch HOT 2
- Support svg images in Xcode inline documentation HOT 2
- Pass "link summaries" instead of "resolved information" in external documentation source responses
- Can't document - -= / /= operators HOT 8
- DocC generates inconsistent output for global Objective-C functions that are renamed to be associated with a type in Swift HOT 2
- Error when publishing to GitHub Pages HOT 6
- Linkable glossary
- Document Objective-C extensions with DocC HOT 2
- Doc Comments Are Ignored for Macros HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from swift-docc.