[feat] Web hosted documentation

[matejmolnar]

This PR aims to solve this ticket

• Remove unnecessary pragma marks
• Add swift setting flag to enable DocC symbol links for code extensions
• Add swift DocC plugin and generate_docs.sh script file for generating static web documentation files
• Move classes related documentation to appropriate files instead of keeping it in documentation.md/README.md
• Update outdated documentation
• Update README with links to the web hosted documentation, which won't be working until we push the changes to master and someone with admin access sets the github pages like so:

[cejanen]

Just sharing first feelings... 793 files changed easily... 🧩

[matejmolnar]

@cejanen I know 😅, but It's mostly generated files for the static web docs.

[cejanen]

Honestly I haven't read all texts but "smekam". I don't know if you used any special tool to generate those texts specially to showcase usage of classes but respect.
So far I'm just curious why do we remove readme file?
Another question. Can I test somehow that the docs will work as expected before merging and updating repo settings as described in PR notes.

[matejmolnar]

Honestly I haven't read all texts but "smekam". I don't know if you used any special tool to generate those texts specially to showcase usage of classes but respect. So far I'm just curious why do we remove readme file? Another question. Can I test somehow that the docs will work as expected before merging and updating repo settings as described in PR notes.

Thank you for the kind words 🙏. No I didn't use any tool to generate the usage documentation.

You can test the documentation by running

swift package --disable-sandbox preview-documentation --target Networking

It will start a local preview server with the documentation.

[johnkodes]

@matejmolnar someone with admin access sets the github pages like so: this is done 👍

[cejanen]

Wanna see it live 🥇

[johnkodes]

I like the changes a lot 🙇 . Few comments 🙏

[johnkodes]

How come that for example TCA doesn't have all of those CSS/JS files 🤔 😄 ? Do you know how can that be achieved?

https://github.com/pointfreeco/swift-composable-architecture/tree/main/Sources/ComposableArchitecture/Documentation.docc

[matejmolnar]

Some projects use a special branch which includes just the documentation, so that's what I though they were doing as well. But upon a closer inspection I found out that it's not the case, but they are actually using Jekyll to build the documentation in a github action

[johnkodes]

Ah, interesting.

They also have the custom branch: https://github.com/pointfreeco/swift-composable-architecture/tree/gh-pages

[matejmolnar]

Ah good catch, how did you find it? 😄 So yeah that's how they do it and they also use Jekyll on top. When I was talking to @cejanen about the separate branch, he said to not worry about it for now and just put the docs into the master branch. But yeah once we would like to also keep multiple versions of the documentation a separate branch is the way to go 🙂

[johnkodes]

I would love if we could have the docs hidden elsewhere (eg. in the separate branch), but this is more than enough ☺️ . Thank you 👍