Docs: Restructure docs folder

[har7an]

Sort of a follow-up to #1315 which revealed a "mismatch" between what the README and docs/ folder immediately provide as info compared to what's actually available.

This restructures the docs/ folder and adds information from various sources to it:

• The README,
• The Wiki
• Examples found in the Wiki

At the moment this duplicates a decent amount of information already available on the Wiki. Strictly speaking this was already the case before this MR, where the README and cross_toml each contained information from the Wiki. My motivation for moving these things into the docs/ folder is that:

1. I'm much more used to finding information in a docs folder than to check for the Wiki. Most projects just don't use the Wiki
2. I usually expect the documentation to be part of what I check out, and the Wiki is not a part of this repo, but its own repo
3. Docs can be updated as part of the same PR that updates the respective code, and arbitrary checkouts of the repo will always contain the docs valid for that version

On a personal note, I much prefer editing text in an editor I'm comfortable with, and Browsers don't fall into that category.

I'm curious to hear your thoughts on this proposed change.

[har7an]

This makes me also want to migrate to a mdbook, which we probably should've done from the start...

Weeeell, I can work out a proposal if you like. In case I do step up to the task: Should we do that in a separate PR?

I'm wondering now though, we should probably edit the wiki with this

Is it really worth the effort in the long run? Especially when moving towards mdbook for documentation, wouldn't it be easier for everyone if there were only one source of documentation for the entire project?

[har7an]

In e636ee5 I've made the cross_toml module in the Rust sources public to eliminate some warnings during building the docs. Now the cross_toml module shows up in the crate documentation, pulling in the content of docs/config_file.md as its' module docs.

While I think it's nice to have that part of the docs mirrored there, unfortunately all the "external" links to other MD docs are broken there. How should we proceed? Imo we have several options:

1. Keep the current state with the broken links
2. Revert the changes, make cross_toml a private module again and remove the #![doc] directive completely
3. Use something like rustdoc_assets to copy the docs/ folder as static assets into the generated docs, making the links in (1) work

Approach 3 seems to rely on build files, tho. I see you're already using xtask, but I have no idea to what extent we can influence how the docs on docs.rs are built, i.e. whether it always runs the same static command, or whether we can tell it to use xtask. Since afaik the docs are built without network access, though, my assumption is that using xtask (which has to compile itself) is out of scope... :(

[Emilgardis]

This makes me also want to migrate to a mdbook, which we probably should've done from the start...

Weeeell, I can work out a proposal if you like. In case I do step up to the task: Should we do that in a separate PR?

That can be done separately. I opened https://github.com/cross-rs/cross/issues/1446 to track it

I'm wondering now though, we should probably edit the wiki with this

Is it really worth the effort in the long run? Especially when moving towards mdbook for documentation, wouldn't it be easier for everyone if there were only one source of documentation for the entire project?

What I meant with editing the wiki is simply just to make it say on each page "see docs/<page> for documentation regarding ..."

While I think it's nice to have that part of the docs mirrored there, unfortunately all the "external" links to other MD docs are broken there. How should we proceed? Imo we have several options:

I think we can just remove the doc from the rustdoc, it's not needed and we can instead just point to the files in the crate package. The only reason its done was because the cross_toml.md file used to be the module documentation for that file https://github.com/cross-rs/cross/commit/bc54c2a37fa0976c7047a20961a3179460d5c619#diff-a93d7b71ff09816ff274b195eaafc678ec01ab637abfe3ce49c0a14dfec32913

[har7an]

Sorry for the slow responses!

What I meant with editing the wiki is simply just to make it say on each page "see docs/<page> for documentation regarding ..."

I see. Will you do that once this is merged, or should I?

I think we can just remove the doc from the rustdoc, it's not needed and we can instead just point to the files in the crate package.

Alright, got it. Now I have:

1. Made cross_toml a private module again and removed the docs directive from the top, so it has no module docs anymore.
2. Added a reference to the docs/ directory in the repo to the "root" crate docs (next to README and wiki).
3. Fixed a remaining link pointing to Cross.toml, which now points to the config_file.md file instead.

What do you think?

[har7an]

@Emilgardis That first rebase was a little too eager, sorry... Changes are in now!