Does DocC handle the root README file for a package hosted on a Git server?
Currently, DocC doesn’t process Markdown files outside of documentation catalogs ( .docc file extension). You bring an interesting use-case though, since READMEs are often a source of documentation—where in the generated website would you expect that content to appear?
Also, I think there might be an interesting distinction in the intent of READMEs vs. package documentation, since READMEs often contain information specific to contributors of the project rather than users, which you might not want to publish as-is in your docs website.
I don't have a clear response. The readme file in a git depository is the first source of informations for users that arrives on the project. The same is true for the main page of a package.
It make sense for a package to have links to the programming elements of the package (structures, classes, protocols…). The readme file in a git depository is often a one file documentation with description, examples. It's different for a package when information is more hierarchical.
But I often copy/paste informations to/from the readme and the entry page of a package as a part of the information is common to both, and sometimes I'd like to have only one place to make changes.
I didn't even think about the web diffusion of the package documentation. For the moment I only use the visualization of the documentation with Xcode or on the git repository.