Better display/search for rules documentation

[noahsark769]

Hey! I know this issue isn't in line with the organization's issue templates, so feel free to redirect or close this if it's not relevant or is being addressed already.

It's pretty tough to look up a specific Swiftlint rule in order to find out what it does, whether it's on/off, what parameters it takes, etc. It seems that the current way to do this is to look for the rul in https://github.com/realm/SwiftLint/blob/master/Rules.md, but this markdown file has become so large that Github doesn't render it with markdown, and in fact (for me) Chrome takes a long time to render the whole page, so cmd-F doesn't work. The only workaround is to clone the repo and use cmd-F in your editor of choice, it seems.

It would be really nice to:

1. Have a better source of truth for rules, their descriptions, their parameters, etc - does this exist anywhere other than the markdown file right now?
2. Have a website where you could filter through all the rules. I'm not sure if Swiftlint has a website other than the github page right now, but I've done this sort of data-driven, static website a couple of times now, with CIFilter.io and sfsymbols.com, and it usually ends up working out pretty well. Hosting is easy and free with github pages, you can update the website on push to master, etc. I don't have a lot of time to devote to this at the current moment, but I'd be happy to work on it on and off when I have some free time soonish. Happy to either commit this to the main swiftlint repo, or maintain my own repo which uses the same data (though we'd have to agree on a shared format in the latter case)

An example sketch of the work for this might be:

1. Parse the markdown to generate some format (yaml?) specifying the name, description, parameters, etc for every rule
2. Start using that format to autogenerate the markdown file
3. Take that format and use it to generate a static site
4. Get rid of Rules.md entirely

Thoughts? @jpsim or others :)

[marcelofabri]

Rules.md was introduced as a more visual way to search for docs as I have 0 design skills. It's generated by SwiftLint itself. You can check how it's done and use that to generate a yml or the static site itself. I think that'd be very welcome.

This is a good starting point: https://github.com/realm/SwiftLint/blob/master/Source/swiftlint/Commands/GenerateDocsCommand.swift

[noahsark769]

@marcelofabri oh nice! Yes, that will be much easier to work with.

Do you have a preference on whether to maintain these docs in this repo vs somewhere else? I could also set it up initially and then move it in, if you folks are okay maintaining a Gatsby/react app in here. Another idea would be to just generate the yaml and commit it to this repo, and have a separate web app which requests the GitHub-hosted files on the fly (this has the advantage of always being able to stay up to date with the current master).

Also, when does this script get run? Every push?

[marcelofabri]

Do you have a preference on whether to maintain these docs in this repo vs somewhere else? I could also set it up initially and then move it in, if you folks are okay maintaining a Gatsby/react app in here. Another idea would be to just generate the yaml and commit it to this repo, and have a separate web app which requests the GitHub-hosted files on the fly (this has the advantage of always being able to stay up to date with the current master).

I personally think it'd be best to host it somewhere else just to reduce the complexity/maintenance cost of this repo. I'm fine with generating an yaml file and commiting. What do you think? Would also love to hear other maintainers' thoughts

Also, when does this script get run? Every push?

There's an unit test that fails and updates the file when its contents are outdated: https://github.com/realm/SwiftLint/blob/master/Tests/SwiftLintFrameworkTests/DocumentationTests.swift#L24

[noahsark769]

Nice, good to know! I'll update that test as well.

Yep, I think going with committed yaml is a good plan. I'm happy to take the lead on writing a webapp which can request it after it's being generated, and I can maintain that separately.

[marcelofabri]

Awesome, thanks for looking into this!

[jessesquires]

Following up on this issue because I was going to offer to do a similar thing. Rules.md is a bit out of control. Any progress here @noahsark769 ?

IMO, using a docs/ folder with GitHub pages would be easier and simpler, especially since the Rules.md is auto-generated.

You could even just use Jazzy to do this -- it supports rendering regular markdown files. And it can be easily automated.

This could be done in an afternoon and it would be a massive improvement on the current state, and a very low maintenance burden.

[noahsark769]

This has been on my backlog for a while and I haven’t had time to look at it yet - I think using Jazzy to generate some docs would be great, and more folks in the iOS community will be familiar with it. @jessesquires definitely feel free to start working on it if you’re up for it!

[jessesquires]

FWIW, I just wanted to see how this would look with basic GH pages.

I forked the repo, moved Rules.md to docs/, renamed it to index.md and configured GH Pages in the repo settings with one of their templates.

It needs some work, but it's a good proof of concept.

I think Jazzy could handle the rendering better.

---

Perhaps longer term, the script that generates Rules.md could be modified to have a separate file per rule. Seems untenable to keep adding to a single file in the long term.

[noahsark769]

Nice, even just having everything collapsed by default makes it way easier to read (and ostensibly to cmd-f)

[jpsim]

Thanks everyone for your suggestions! I've started working on integrating jazzy to document both SwiftLintFramework's API and these rules. I'll report back here when I have something meaningful to share.

[jpsim]

Got something working here: https://github.com/realm/SwiftLint/pull/3016

But unfortunately the GitHub org where this project is hosted is on a "legacy" GitHub plan so I can't continue with my preferred approach of using a GitHub action to push the doc updates to GitHub Pages.

I'll need to spend a bit more time to get that CI job to work on Azure Pipelines instead.

[jpsim]

Addressed in #3016.

[noahsark769]

Amazing! Thanks so much for your work on this, @jpsim! Looks like https://realm.github.io/SwiftLint/rule-directory.html will satisfy the issues I first posted.

(One note: maybe we could link to the generated Jazzy docs in the repo's main URL? Currently it links to realm.io)

[jpsim]

(One note: maybe we could link to the generated Jazzy docs in the repo's main URL? Currently it links to realm.io)

Done, thanks for the idea.