Fix links in and display of documentation

Question

There is a number of problems with the way the documentation is made available and interlinked:

• Currently most people likely arrive to https://github.com/clojure/core.contracts and read the README - but it does not point to the docs in {{./docs/}} => add link to it there
• It is not clear how the docs are expected to be browsed; I suppose that the .org
  files should be exported to * } yet not all of them are. I also
  suppose that the exported markdown files should be available under https://github.com/clojure/core.contracts/wiki, i.e. pushed to git@github.com:clojure/core.contracts.wiki.git
• Some of the problems:

   *  the link "return to documentation" on e.g. "with-constraints" should point to /clojure/core.contracts/wiki, not /clojure/core.contracts/docs.html
  

  • if wiki is really exported, the main page should mention it is immutable
  • links on the home page had one more 'wiki' in them (fixed manually in the wiki - will be overriden by the next export)
  • some links are broken, f.ex. (link: defconstrainedfn)(/clojure/core.contracts/wiki/defconstrainedfn) on f.ex. {{contract}}; (link: with-constraints)(/clojure/core.contracts/with-constraints/) (missing /wiki/), (link: defcontract)(/clojure/core.contracts/wiki/defcontract/)

It would certainly help the project if the documentation was easier to access and browse :-)

Thank you

Answer 1

Reference: https://clojure.atlassian.net/browse/CCONTRACTS-5 (reported by alex+import)