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)
- Theme like developer.apple.com/documentation
- Interactive tutorial for building interactive tutorials
- Tutorial code delta not picking up changes in some cases
- Linkable glossary
- Document Objective-C extensions with DocC HOT 2
- Xcode "Build documentation" not working with Swift Macro package in project HOT 5
- Curating a module under a technology root causes the sidebar to not show Objective-C symbols
- illegal hardware instruction HOT 4
- This mangled quote/code fence results in a crash HOT 1
- `@DeprecationSummary` directive doesn't always have an effect HOT 2
- Xcode does not provide fix for operator functions HOT 4
- Make DocC-Generated Website Indexable by Search Engines HOT 2
- Slices of Snippets don't have indentation removed HOT 1
- optional force unwrap fails if target name contains special characters
- Snippet slicing does not handle multiline string literals correctly
- Migrate to Swift 6
- Deprecated Objective-C methods not being marked as Deprecated
- Add `*` support for `@Available` directive HOT 2
- Remove duplicate semantic versioning types HOT 1
- DocC cannot generate documentation for tuple containing multiple parameter packs.
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.