How is this going to work? about specification

[xuhdev]

I'm planning to use sphinx and have pages automatically generally either by readthedoc or by us. Any suggestions?

[xuhdev]

readthedocs is a website that pulls git repositories and runs sphinx over them. We always have everything in a git repository, so git history will always be available. Readthedocs also builds a version for every tag, which I think should be sufficient for a web version. But nonetheless, IMO it's better to have a changelog somewhere, in addition to indication of versions inside various spots of the doc.

[xuhdev]

Sorry for the delay -- I've made the first commit. The content is mostly copied from the C header file and the homepage. We probably have a lot of details to fill in. Feel free to open issues and make PRs regarding the current version!

Closing this issue now as the basic engine is chosen.

[cxw42]

I support the idea of GH pages. Using the GH wiki probably isn't such a good idea for something that is supposed to be a stable reference :) .

I would also recommend, besides the latest in /, keeping earlier versions in /old/x.y.z (or some such). That will make it easier for implementers to see what has changed between versions.

[ffes]

Using the GH wiki probably isn't such a good idea for something that is supposed to be a stable reference :) .

You are very right! I would suggest to disable it in the settings of the repo

[jednano]

FWIW, the wiki has revisions and you can see Git history if you clone it, but that's not very convenient.

I'm a fan of https://www.docz.site/. I used it already on this site.

I don't know that I like keeping older versions of the specification, but a changelog might be in order?

[cxw42]

@jedmao Sure, a changelog is fine with me if you prefer. I suggest moving old versions rather than deleting them because I have found that useful in the past for other projects. (For example, with very few exceptions, you can look back at the full contents of any version of any CPAN module. I have found that very helpful while debugging platform-specific issues.)

[jednano]

@cxw42 how is that different than just looking at Git history?

[cxw42]

Git history is certainly another way of providing access to the information. An online version is accessible to a wider audience, and does not require cloning this repo.

Anyway, does readthedocs or docz keep old versions automatically? This may be a non-issue :) .

[ffes]

readthedocs.org is indeed a nice service to use. I use it for the docs of my projects that have docs. At the office we use self hosted Python Sphinx for all our docs.

Are you going to use markdown or reStructureText? Personally I like rst for docs better because it makes referencing easier (keywords instead of links)

[xuhdev]

Both docz and sphinx use rst. Likely we will use it.