Comments (15)
@swift-ci create
from swift-docc.
Comment by Waheed Afolabi (JIRA)
@d-ronnqvist I have assigned it to myself!
Could you please show me the direction to follow now!
from swift-docc.
Great! I'll post a comment with more information later today or tomorrow.
from swift-docc.
A important note
Since this is a user facing change with potentially new syntax, we would want to make a small pitch in the forums for the proposed solution (not the full evolution process, just a small post so that the community can discuss the user impact). I can help you with the pitch but the discussion is not going to conclude until sometime after the new year when people are back from vacation.
If you still want to work on this, I'll outline the design that I've been thinking of and directions for how to implement it. Just note that this design hasn't been discussed in the forums, so the final design may change.
If the pitch and discussion portion feel like to much for a first contribution I've also opened SR-15634 earlier today and left a comment with some directions of how that could be implemented.
My proposed design
The user facing changes that I've imagined here is to introduce a new @DisplayName
directive that would be a child of the existing @Metadata
directive. Developers would add this directive to customize the title that's displayed for a given module in the documentation extension for that module. For example:
# ``ArgumentParser``
@Metadata {
{{ @DisplayName("Swift Argument Parser")}}
{{}}}
Straightforward, type-safe argument parsing for Swift.
...
This would allow for per-page customization when a symbol's name isn't the preferred display name. (A framework's top level page represents the frameworks "module" symbol.
DocumentationExtension
is an example of how such a directive could be implemented and the Metadata
directive would also need to updated to parse that from its child content
With that information available on the documentation extension, when a DocumentationNode
is initialized with a symbol and a documentation extension it would check if the documentation extension has specified a custom display name and set its name to a Name.conceptual(title🙂
instead of the Name.symbol(declaration🙂
. It may also be necessary to do the same check for a custom display name in initializeSymbolContent(documentationExtension: engine:
. I believe that only the node's name
needs to change to control how the page's title.
MetadataTests
has existing tests specific to how the the @Metadata
directive parses its content.
This test in SemaToRenderNodeTests.swift could serve as a starting point for how to test the full flow of providing a custom display name in a directive in the documentation extension, verifying that that documentation node's name is correct, rendering that node and verifying that the render node also contains the right title (the render node's metadata
hold the title
for the page).
from swift-docc.
Also, If you want to implement this but not do the pitch, then I can post a pitch for this sometime after the new year.
from swift-docc.
Comment by Waheed Afolabi (JIRA)
@d-ronnqvist Thanks for your time and providing this guidance.
I'd love to implement this, as well as make the pitch but I haven't done one.
I don't know how to, but I want to start doing it![]( So, I might need some guidance on it)
After the new year is cool!
from swift-docc.
Comment by Waheed Afolabi (JIRA)
While trying to see how a pitch is done, I found this:
https://forums.swift.org/t/modify-accessors/31872
I see a pattern, however I am not sure if this particular one is too complex to study for the goal at hand, or if you have a simpler one you could point me to as a reference.
from swift-docc.
Swift-DocC uses a slightly simplified pitch/proposal process compared to the broader Swift Evolution process.
Here are a few examples of previous pitches for Swift-DocC:
-
https://forums.swift.org/t/improve-presentation-of-non-framework-documentation-sr-15434/53388
-
https://forums.swift.org/t/extending-swift-docc-render-json-to-support-multi-language-symbols/52881
-
https://forums.swift.org/t/extending-swift-docc-to-support-objective-c-documentation/53243
-
https://forums.swift.org/t/support-hosting-docc-archives-in-static-hosting-environments/53572
This is how I would describe the current format:
-
A brief description/summary of the problem.
-
Motivation (optional): An explanation of what benefit will be provided by solving the problem. This can be left out if the benefit is clear from the problem description.
-
Proposed Solution: A high level overview that describe the intended solution.
-
Detailed Design (optional): A more in-depth description of the solution. This can be left out if most of the design is already described by the high level overview above.
-
Alternatives Considered (optional): An even briefer description of any alternatives that were considered and their drawbacks compared to the proposed solution.
from swift-docc.
waheedNowLovesSwift (JIRA User) I talked to some of my colleagues about this. We discussed two alternatives—one alternative was specifying the display name in the h1 heading and using a directive to associate the file with the symbol and the other alternative was using a different link syntax in the h1 heading—but we think that the @DisplayName
directive is the better solution.
Unless you really want to write the pitch, I offering to write the pitch for this but leave the implementation to you. Pitching a design for an enhancement is above and beyond what we'd expect for a first time contribution.
from swift-docc.
I will probably post a pitch for this sometime next week. After that we'll want to give the community at least a week to provide their feedback.
from swift-docc.
I posted a proposal for this here https://forums.swift.org/t/support-customizing-the-display-name-for-symbol-documentation/55169
from swift-docc.
waheedNowLovesSwift (JIRA User) I may try and implement this later this week or early next week.
from swift-docc.
Comment by Waheed Afolabi (JIRA)
@d-ronnqvist great to know you've done the proposal...
Is there a way I could work along, I seem blacked out on how to move!
from swift-docc.
waheedNowLovesSwift (JIRA User) I've started working in this here but there are still a few pieces remaining if you want to work on that. Let me know and we'll figure our a way to collaborate on it.
The Directive turned out to be harder to implement than what I originally intended and I needed to make some swift-markdown changes here to support an initial argument without a label / name.
from swift-docc.
This PR is merged now.
from swift-docc.
Related Issues (20)
- Swift-DocC should display C++ and Objective-C++ as their own source languages
- 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
- 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
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.