Comments (5)
@swift-ci create
from swift-docc.
We'll use this bug to track support specifically for `docc convert --transform-for-static-hosting --enable-experimental-custom-templates`.
Support for `docc archive transform-for-static-hosting --enable-experimental-custom-templates` is tracked separately with SR-15750.
from swift-docc.
I think this would be a good starter issue. Here's some thoughts on how to get started:
DocC's transform for static hosting logic for docc convert
follows this general code path:
- ConvertAction.swift#L319: Check if a copy of Swift-DocC Render has been provided and find the URL for the
index.html
it contains. If the user has provided a custom hosting base path, use thetemplate-index.html
and do some string replacement to write out a customindex.html
and save that URL. Primary goal of this section is to get the URL for theindex.html
file that needs to be copied around for static hosting. - ConvertAction.swift#L372: Pass that
index.html
URL to the convert action's file writer. - ConvertAction.swift#L378: Begin the conversion process.
- DocumentationConverter.swift#L293: Documentation converter converts an individual render node and passes it to the file writing consumer.
- ConvertFileWritingConsumer.swift#L61: File writing consumer passes the render node to the render node writer.
- JSONEncodingRenderNodeWriter.swift#L120: The render node writer creates a copy of the
index.html
in the currently building DocC archive (provided by step (2)) to a path relative to where the current render node being written in thedata
directory.
Separately, in ConvertFileWritingConsumer
there's logic that picks up any provided custom header/footer templates and injects them in to that same index.html
at the root of the DocC archive: ConvertFileWritingConsumer.swift#L191.
Unfortunately, the ConvertFileWritingConsumer
is provided the custom header/footer templates after it's already written out all of the render nodes, and thus copied around the index.html
without the injected header/footer.
- DocumentationConverter.swift#L293: Documentation converter converts an individual render node and passes it to the file writing consumer.
- DocumentationConverter.swift#L333: Documentation converter passes all of the bundle's assets (including the custom header/footer templates) to the file writing consumer.
And so we end up in the situation where the index.html
file at the root of the emitted archive has the correctly injected custom header/footer, but all of the other index.html
files for each individual render node are incorrect.
I believe the simplest fix here would be to just move the call to try outputConsumer.consume(assetsInBundle: bundle)
in DocumentationConverter
before any calls to try outputConsumer.consume(renderNode: renderNode)
. This would ensure that whenever the output consumer consumers a render node, the index.html
in the output archive is the correct, already transformed one.
An alternative solution would be to move the logic for injecting custom header/footer earlier in the process.
Either way, we'll need to add a test that ensures that when a bundle that includes a custom header/footer is converted with support for static hosting, that custom header/footer is included in all of the copied index.html
files. For that, I would create new copy of testConvertWithCustomTemplates() that converts a bundle the includes actual content (that can be done by adding a symbol graph to the folder used as input). Then assert that the each of the copied index.html
files also have the expected content just as the current test is asserting that the one at the root does.
from swift-docc.
@ethan-kusters can this be closed with the merge of #410?
from swift-docc.
@mportiz08 Yes! Thank you for the ping.
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.