Update readme

[kimdv]

I was think if we should SwiftSyntax specific info from root readme into a new readme inside SwiftSyntax source, just like SwiftSyntaxBuilder.
The same for SwiftSyntaxParser.

Then keep the root readme to things that is common for all sources?
Like how to get started developing, report bugs, license etc?

[ahoppen]

I was think if we should SwiftSyntax specific info from root readme into a new readme inside SwiftSyntax source, just like SwiftSyntaxBuilder. The same for SwiftSyntaxParser.

Then keep the root readme to things that is common for all sources? Like how to get started developing, report bugs, license etc?

I would actually prefer to go the other way because I think the readme in Sources/SwiftSyntaxBuilder is not very discoverable and I think the three modules should always be considered together since you don’t have to make a choice and use either one or the other. But then the top-level readme is already getting quite large. What I’m thinking might be beneficial would be to create top-level “Documentation” and “Examples” folder that contains all the documentation that’s not necessary to get started.

The Documentation folder would include documents to

• Declare SwiftPM dependency with nightly build
• Embedding SwiftSyntax in an Application (includes Embedding in an iOS Application)
• Contributing

The examples folder would contain

• A markdown document with example users
• .swift files with for the examples we currently show (AddOneToIntegerLiterals and your example to use SwiftSyntaxBuilder)
  • In CI we could also make sure that these examples actually compile. I just noticed that the example in the main README doesn’t even compile because it doesn’t import SwiftSyntaxParser (as a follow-up change)

The main README.md would then include links to the documents in the Documentation and Examples folder. What do you think?

[kimdv]

I would actually prefer to go the other way because I think the readme in Sources/SwiftSyntaxBuilder is not very discoverable and I think the three modules should always be considered together since you don’t have to make a choice and use either one or the other. But then the top-level readme is already getting quite large. What I’m thinking might be beneficial would be to create top-level “Documentation” and “Examples” folder that contains all the documentation that’s not necessary to get started.

Agree on that it can be hard to find and a single readme will become to large and messy.

What about using DocC?
I have seen the documentation from DocC itself. It looks really good. We have the possibility to make guides, how to get started, examples etc.
They have recently added support for static hosted sites: swiftlang/swift-docc#56

The Documentation folder would include documents to

• Declare SwiftPM dependency with nightly build
• Embedding SwiftSyntax in an Application (includes Embedding in an iOS Application)
• Contributing

I think that contributing should be in the main readme as for me it is more "repository" related documentation on how to contribute, where SwiftPM and SwiftSyntax embedding is more documentation for how to use it.
Can you follow me?

The examples folder would contain

• A markdown document with example users

• .swift files with for the examples we currently show (AddOneToIntegerLiterals and your example to use SwiftSyntaxBuilder)

  • In CI we could also make sure that these examples actually compile. I just noticed that the example in the main README doesn’t even compile because it doesn’t import SwiftSyntaxParser (as a follow-up change)

It would be pretty cool if we could make the CI actually test/compile the examples. 💪

The main README.md would then include links to the documents in the Documentation and Examples folder. What do you think?

And then I think the contribution, license, issues and so on is added in the main readme.

[ahoppen]

What about using DocC? I have seen the documentation from DocC itself. It looks really good. We have the possibility to make guides, how to get started, examples etc. They have recently added support for static hosted sites: apple/swift-docc#56

Exploring to use DocC would definitely be interesting but there’s a non-trivial deployment story we need to solve. We always want the latest documentation for the current main branch. But that means that we need to do one of the following

• You need to manually rebuild the documentation when you make any changes
  • I think this is not practical
• We need to have a CI job that generates and pushes the documentation to a different repository
  • In that case we wouldn’t have any documentation inside this repository itself, which I don’t really like but maybe having a basic README + reference to the DocC-generated documentation would be alright
  • Creating a new repository + the necessary CI job is not something we can set up in the short-term
• We require users who wish to view the documentation to download the repository and open the documentation themselves
  • I think this raises the entry barrier of figuring out what SwiftSyntax too much because cloning/downloading the repo just to view the basic documentation seems like a fairly big commitment to me

I might have missed an option here because I’m not familiar with DocC but I would suggest that for now we stick with markdown files.

As a separate task, we could consider improving the doc comments of SwiftSyntax to generate better documentation which adopters can build themselves by invoking docc locally.

I think that contributing should be in the main readme as for me it is more "repository" related documentation on how to contribute, where SwiftPM and SwiftSyntax embedding is more documentation for how to use it. Can you follow me?

I disagree here. This repo is the main entry point to whoever wants to use SwiftSyntax as a Swift package dependency and I expect those to be the vast majority compared to those who contribute to the repository. So I think the documentation should primarily target adopters of SwiftSyntax. Contributors are already slightly more committed and I think we can expect them to click a link to view the “Contributing” documentation.

And then I think the contribution, license, issues and so on is added in the main readme.

I’m not entirely sure if I understand what you mean here but my idea is that the main readme is fairly lightweight. IMO “Contributing” and “License” should just be links. If the documentation to write bug reports it might fit into the main readme.

[kimdv]

Exploring to use DocC would definitely be interesting but there’s a non-trivial deployment story we need to solve. We always want the latest documentation for the current main branch. But that means that we need to do one of the following

• You need to manually rebuild the documentation when you make any changes

  • I think this is not practical

• We need to have a CI job that generates and pushes the documentation to a different repository

  • In that case we wouldn’t have any documentation inside this repository itself, which I don’t really like but maybe having a basic README + reference to the DocC-generated documentation would be alright
  • Creating a new repository + the necessary CI job is not something we can set up in the short-term

• We require users who wish to view the documentation to download the repository and open the documentation themselves

  • I think this raises the entry barrier of figuring out what SwiftSyntax too much because cloning/downloading the repo just to view the basic documentation seems like a fairly big commitment to me

I might have missed an option here because I’m not familiar with DocC but I would suggest that for now we stick with markdown files.

As a separate task, we could consider improving the doc comments of SwiftSyntax to generate better documentation which adopters can build themselves by invoking docc locally.

Let's wait with DocC then, and getting started with some basic documentation then.

I disagree here. This repo is the main entry point to whoever wants to use SwiftSyntax as a Swift package dependency and I expect those to be the vast majority compared to those who contribute to the repository. So I think the documentation should primarily target adopters of SwiftSyntax. Contributors are already slightly more committed and I think we can expect them to click a link to view the “Contributing” documentation.

I have tried to make folder structure so it's easy to navigate to the correct folder.

I’m not entirely sure if I understand what you mean here but my idea is that the main readme is fairly lightweight. IMO “Contributing” and “License” should just be links. If the documentation to write bug reports it might fit into the main readme.

I have tried to structure what I have been thinking of.

How to setup the CI to test the examples, I don't know 🤷‍♂️

[ahoppen]

I think we could put those example users in the Examples folder.

[kimdv]

I have moved those, and called I Some Examples Usages (I think the Users is a typo)

[ahoppen]

@swift-ci Please test