cljdoc setup

[martinklepsch]

Hi @weavejester, since you previously mentioned that cljdoc might be interesting for you I thought I'd help you get started by making the necessary changes to compojure. This PR follows a similar procedure as one that I made to muuntaja:

• Move all guides from the wiki into the repo, this ensures they are versioned alongside the actual code and allows cljdoc to relate releases and versions of guides.
• Drop some pages of the wiki that seemed no longer relevant.
• Add a doc/cljdoc.edn file that outlines all articles as they are going to be shown on cljdoc
• Replace all links to wiki pages with links to the versions on GitHub or cljdoc.
• Add a cljdoc badge to the README:
• I added a list of interesting pages to the README as well as a pointer to an API overview page.

For the last point we could also link to the files in doc/ if you would prefer that. Then people on GitHub will stay on GitHub to view articles (cljdoc will pick up those links and rewrite them when rendering the markdown on cljdoc.xyz).

While usually you cannot retroactively update documentation for a release (at least not yet) I cheated a bit so you could see the end result of this change: Compojure on cljdoc.

Let me know what you think, I hope this is helpful 🙂 (but also, don't worry if you're not yet ready to make the jump)

EDIT Note that there are two issues, both related to wikilinks:

1. https://cljdoc.xyz/d/compojure/compojure/1.6.1/api/compojure.response#Renderable
2. https://cljdoc.xyz/d/compojure/compojure/1.6.1/api/compojure.route#not-found

Codox handles both of these fine. Wiki links in the same namespace already work fine but I'm intending to make wiki-links work cross-namespace too. I would however prefer a more explicit fully-qualified variant, e.g. [[compojure.core/GET]]. Let me know if you have any thoughts on that.

[weavejester]

Thank you for the PR, but I don't want the information in the wiki moved into the repository.

I may add documentation to the repository under a "docs" subdirectory, but I'd rather I write this from scratch, rather than just copying what's currently in the wiki.

I'd also want to keep the wiki for some information, as the wiki provides a convenient place for people to contribute documentation or examples to, without requiring a pull request. For example, I might have the in-repository docs detail the syntax and use of the library, while the wiki contains links to third-party libraries, code examples, specific use-cases and other "additional" documentation.

Regarding the wiki links, they should already work across namespaces. If they unqualified, Codox assumes they're in the same namespace. If they're partially qualified, Codox looks for the nearest match. If they're fully qualified, Codox uses the exact namespace and symbol to generate the link.

[martinklepsch]

Got it. In this case should we close this PR until those new docs get written or would you like to merge. some of this regardless (maybe only some "core" documentation)?

I'd also want to keep the wiki for some information, as the wiki provides a convenient place for people to contribute documentation or examples to, without requiring a pull request. For example, I might have the in-repository docs detail the syntax and use of the library, while the wiki contains links to third-party libraries, code examples, specific use-cases and other "additional" documentation.

I found that most of the wiki pages (except "Emacs Indentation" and "Common Problems" maybe) actually fit fairly nicely into "syntax and use" of the library but I definitely see the point of having something that doesn't require explicit approval. (Note that all articles on cljdoc have an Edit on GitHub to make contributing as easy as possible.)

Regarding the wiki links, they should already work across namespaces. If they unqualified, Codox assumes they're in the same namespace. If they're partially qualified, Codox looks for the nearest match. If they're fully qualified, Codox uses the exact namespace and symbol to generate the link.

The cljdoc UI isn't codox (just using it as analyzer) so there are some differences here and there.

[weavejester]

Got it. In this case should we close this PR until those new docs get written or would you like to merge. some of this regardless (maybe only some "core" documentation)?

I think close. I don't think there's anything I want to use without altering first.

I found that most of the wiki pages (except "Emacs Indentation" and "Common Problems" maybe) actually fit fairly nicely into "syntax and use" of the library but I definitely see the point of having something that doesn't require explicit approval.

Have you considered pulling documentation from the wikis as well? They're just git repositories of markdown files AFAIK, so accessing them should be straightforward.

The cljdoc UI isn't codox (just using it as analyzer) so there are some differences here and there.

Ah. But it could be made to work like Codox? I don't like the idea of fully qualifying namespaces when I don't need to. It makes the raw docs harder for people to read without formatting.

[martinklepsch]

Have you considered pulling documentation from the wikis as well?

I have but the issue with that is that you cannot "link them in time". If I have a version tag or a SHA in a projects .pom file I can fetch the respective version of the documentation. For a wiki I don't know of a way to do that.

But it could be made to work like Codox?

It could but it would require a lot more information in the piece of code that is responsible for rendering vars/docstrings and to keep things simple I'll probably defer that until later.

I'll close this PR then but please reach out if there's anything I could do to help you get set up (also happy to make similar PRs to other projects if there are some which are better suited).