Build a tool similar to SwiftDoc.org for SwiftPM

Development Package Manager
,
#1

It would be very interesting and valuable to build a graphing tool to expose the hierarchy and interaction between modules classes, methods, etc in the SwiftPM project.

Something like:

35%20PM
Screen Shot 2018-08-09 at 7.32.35 PM.png1279Ă—381 33.6 KB

This would be very helpful to understand the project structure, and it will make it easier to contribute to it.

Process:

  1. Information gathering
  2. Thoughts
  3. Help

1. Information Gathering

I asked @Mattt [who contributes to SwiftDoc] about how can we get the information to build this documenting/graphing tool and he pointed out:

Equivalent information can now be surfaced by SourceKit directly when run on any Swift code (no derived headers required).

Which is better for us because we can lean on SourceKit or SourceKitten to build this tool.

Is it better to build this tool on top of SwiftDoc or to make it from scratch?

I asked something similar to @Mattt and he answered:

The code of SwiftDoc.org could be used to bootstrap such an effort, but my personal opinion is that a new, “clean room” implementation would be a better solution.

2. Thoughts

I started to dig a little more into this, and there are two tools that can be very helpful for us to build this graphing tool:

  1. SourceKitten

  2. Jazzy

Initial idea

The initial idea is to build a tool that uses SourceKitten and generates a JSON ready to be graphed, I mean, a more friendly JSON that relates the different parts of the SwiftPM project.

Then, on top of that we can build different graphing tools that expose better the SwiftPM project.

Also I think we can generate documentation with Jazzy and complement the graphing tool with this docs.

We need to improve the SwiftPM docs before start generating docs with Jazzy.

General idea, wraping up:

  1. Build a parser on top of SourceKitten that generates a JSON that makes it easier to relate all the modules/classes/functions, etc.

Let's call this "parser" SwiftPM SourceGrapher
or just Swift SourceGrapher if it can be used on any Swift project

  1. Improve SwiftPM documentation to generate docs with Jazzy.

  2. Build documenting/graphing tools on top of SwiftPM SourceGrapher.

  3. Make a site with all this tools, something similar to SwiftDoc

3. Help

  1. The SwiftPM SourceGrapher should be SwiftPM specific or if it can target any Swift project?

  2. What are other ways to accomplish this?

  3. Any other useful tools that I didn't mentioned?

P.S.
I am very new to all of this; correct me if I am making naive asumptions or something similar.
Please share tips and ideas for building this useful tool that can improve how developers join and contribute to the SwiftPM Project.

6 Likes
#2

This could definitely be useful for any Swift projet! We can use GraphViz for generating the graphical representation.

1 Like
#3

This sounds like a great idea to work towards, I would love it if SwiftPM exposed better support tooling in this area (documentation generation, etc).

If you are leaning on jazzy / SourceKitten, one of the first things we would need to figure out is how to interface with those systems...

#4

Adding support for SourceKit in SwiftPM will be a good start and we can use that support for building many features. SourceKit already has some Swift bindings that we should use and possibly expand.

#5

Hi Daniel,

  1. Can you please elaborate a little more on this?

  2. When you say we need to figure out how to interface with those systems, is this tool we are talking about going to be integrated within the SwiftPM project? or are you saying we need to build something inside SwiftPM to let <tools as "Swift SourceGrapher"> benefit from that?

thanks

#6

Hi Ankit,

  1. Can you please name a few of those features we can build?

  2. Is there any specific "challenge" or similar when integrating SourceKit to SwiftPM?

  3. Why SourceKit instead of (for example) SourceKitten? Does it has to do with SourceKit being part of the Swift project? (I am asking just for curiosity, I have no preference for one or the other)

#7

  1. On top of my head: documentation generation, automatic test method generation for linux, API checker for semver.

  2. There is no “new” challenge, its just something that needs to be done. This is similar to how SwiftPM links with llbuild, foundation, dispatch libraries.

  3. Yes, SourceKit is already a part of the Swift OSS project so it makes sense to use it directly.

1 Like