First phase of migrating the wiki to the internal docs #11078

[alan-andrade]

This is not done yet but I'm posting it to get feedback.

The wiki has a ton of different tutorials/manuals/faq and so forth. Instead of migrating all of them right now, I just migrated the following:

• The general main wiki page
• Language FAQ
• Project FAQ

If this feels reasonable, please comment so that I can continue with confidence.

[emberian]

I'm quite OK with this.

cc @alexcrichton @brson @steveklabnik @chris-morgan

[asb]

Issue #5831 is relevant to this PR (and probably means it can not be blindly merged).

[emberian]

Yikes, that's a pain.

[alan-andrade]

Every internal Manual, Guide (Tutorial) or other Documentation, could contain the License at the bottom declaring the double license as per COPYRIGHT.txt

How does that sound ?

After approved we could deprecate the wiki ?

[emberian]

@alanandrade that isn't the problem, the problem is that the wiki basically has no license at all. Everything is copyrighted by the author.

[alan-andrade]

I'll ask every author for the copyright transfer. The official permission would be a comment on this pull request.

This won't be merged until we get every author grant and we all agree the terms.

[alan-andrade]

According to last commit.

Assumptions:

• author = Contributor that either started or edited a wiki page.
• license. every page will contain the double license notice at the bottom.

That means we need the permission of 11 contributors according to this page: https://github.com/mozilla/rust/wiki/Doc-language-FAQ/_history if we want to merge the Language FAQ page transcription.

Do we need the permission of contributors that only changed small portions ?
In the case we don't, then @brson is the real author of both FAQs (Lang and Project). How should we proceed with your copyrighted material ?

About the plan

It feels sloppy :( but I don't know what to do to solve it faster and effectively.

[steveklabnik]

I like this idea.

The license issue is tricky. Theoretically you need every contributor to sign off...

[adrientetar]

The file that lists users groups and so forth sounds wiki-ish to me.

[brson]

I want to get this merged for 0.9.

Let's move forward with the transfer and ignore the licensing issues for now. I'll talk to the lawyers about what we should do with the documentation licensing.

I'd like to make some changes though:

• Get rid of license.md until we know the right thing to do
• Move other.md to index.md to make it the landing page for all documentation.
• Add links to all the documentation from index.md
• Remove blogs from index.md
• Add a link to the wiki to index.md

I'm not sure about the community stuff, but I'm inclined to leave it there so people can find it easily.

Sorry I took so long to look at this.

[alan-andrade]

All right, we have the most important wikis here.
@brson suggestions were applied.

Ready for review or +r stuff ;)

[adrientetar]

@alan-andrade You still have license.md in here.

[alan-andrade]

@adridu59 My bad, I believe its ready now.

[adrientetar]

This should definitely stay. manual.inc is here to overwrite this rule for select files.

However tutorial + guides should keep this rule, at least this is the current policy.

[alan-andrade]

I thought this could be better done by passing --toc-depth=1 to pandoc by default.
Also, I'm interested in using a depth of 2 for FAQs

[alan-andrade]

Oh, I see the connection of what you're saying.

Of course I want to go with the current policy, but my gut is telling me that overriding CSS just to hide ul's is not very clean. If we have an option to not even display the uls that we don't want, then why not use it ?

[adrientetar]

For the record, display: none doesn't hide, it just doesn't display; hiding would be visibility: hidden.

[alan-andrade]

@adridu59 ok, hopefully this is the last time I bother you 👍

[adrientetar]

We should only want this for rust.md (Manual) and not for Tutorial/Guides, or are you willing to use it elsewhere?

My understanding is that only the reference manual should have that heavyweight full toc (tutorials are more meant to be followed at least by-section).

[brson]

I agree that all the docs should depend on version_info.html and include --include-before-body=doc/version_info.html in their pandoc command.

[alan-andrade]

oh, and every html will include version_info just as HTML_OPTS describes.

[brson]

Thanks @alan-andrade

[brson]

I think this will fail because tests.mk hasn't been updated to extract tests from the renamed files. Also, @alan-andrade can you update the names of the guides to 'guide' instead of 'tutorial', and update the final section of 'tutorial.md' to refer to additional guides, not 'tutorials'?

[adrientetar]

@brson Wasn't all that done in eeafee4?

[alan-andrade]

@brson @adridu59 rust-lang/prev.rust-lang.org#19