Migrating documentation to docs.citationstyles.org

CSL Development
1

Hi all,

A while back I set up an account with Read the Docs, a free service
for converting reStructuredText documents to HTML and PDF using
Sphinx, and for hosting these files online. I currently keep the
source files at https://github.com/rmzelle/writing, with the rendered
documentation available at docs.citationstyles.org. So far it hosts
our documentation on locale files, and a rewritten version of the CSL
primer.

I’m now considering migrating all long-form CSL documentation from
citationstyles.org/downloads/… to docs.citationstyles.org. This
would affect the CSL specification, primer, and release notes. Unless
people suggest otherwise, I’m planning to:

This move would have several advantages:

Best,

Rintze

2

Oh, and I would have to set up some redirects from e.g.
http://citationstyles.org/downloads/specification.html to the new
location, but it looks like there are simple WordPress plugins for
that.

Rintze

3

Not sure what the hosting capabilities for CSL are, so this might not be
possible, but you could probably shorten your URLs with a little Apache URL
rewriting http://httpd.apache.org/docs/current/mod/mod_rewrite.html

Aurimas

4

So, any opinions on how to best organize our CSL documentation?
http://docs.citationstyles.org/en/latest/ currently has the following
documents:

Primer — An Introduction to CSL
Guide to Translating CSL Locale Files
CSL 1.0.1 Specification (2012-09-03)
CSL 1.0.1 Release Notes
CSL 1.0 Specification (2010-05-30)
CSL 1.0 Specification (2010-03-21)
CSL 1.0 Release Notes

This mirrors the current setup in
https://github.com/citation-style-language/documentation, where we
only use the “master” branch and copy files when we have a release.

The alternative is to adopt a proper Git branch model for
https://github.com/citation-style-language/documentation, so we end up
with something like:

http://docs.citationstyles.org/en/stable/ (default for users visiting
http://docs.citationstyles.org/; mirrors content of latest release)
http://docs.citationstyles.org/en/master/ (for development)
http://docs.citationstyles.org/en/1.0.1/ (for CSL 1.0.1)
http://docs.citationstyles.org/en/1.0/ (for CSL 1.0.1)

I’m leaning towards adopting the latter. However, Read the Docs
recommends the use of Semantic Versioning (see
http://read-the-docs.readthedocs.org/en/latest/versions.html and
http://semver.org/). According to these rules CSL 1.0.1 should
probably have been CSL 1.1. While we probably can get away with that
discrepancy, I’m not entirely sure how to best deal with
specification-only updates, like the 2010-05-30 update we had for CSL
1.0. We could just create a single branch for CSL 1.0, but that would
mean that we couldn’t offer rendered versions of both the 2010-03-21
and 2010-05-30 CSL 1.0 specification releases (but just the latter).
That might be an acceptable loss, though.

Rintze

5

Hi everybody,

I just finished the migration of our long-form documentation from
http://citationstyles.org/downloads/ to http://docs.citationstyles.org/.

http://docs.citationstyles.org/ had existed for a while, but was populated
from https://github.com/rmzelle/writing. I now updated
https://github.com/citation-style-language/documentation/ to be compatible
with Sphinx and Read the Docs, and hooked it up to
http://docs.citationstyles.org/. We now have:

http://docs.citationstyles.org/en/stable/
http://docs.citationstyles.org/en/1.0.1/
http://docs.citationstyles.org/en/1.0/
http://docs.citationstyles.org/en/1.0-20100321/
http://docs.citationstyles.org/en/master/

“stable” always equals the latest version (“1.0.1”). We have git branches
for each CSL version (“1.0” and “1.0.1”), and there is a git tag for the
original 1.0 specification (“1.0-20100321”) (I might hide the latter
because it might be confusing for users). Each version only contains the
release notes for that version. Dan set up redirects for the original
http://citationstyles.org/downloads/pages (e.g.,
http://citationstyles.org/downloads/specification.html redirects to
http://docs.citationstyles.org/en/stable/specification.html).

Since Read the Docs automatically builds documentation when a commit is
pushed to GitHub, it’s now much easier for me to make corrections and to
keep the specification up to date. The HTML is now responsive as well.

Rintze

6

Rintze,

this looks great! One small issue: the „Edit on Github“ links for the „stable“ version are broken, probably because there is no „stable“ git branch or tag. I like semantic versioning for the documentation.

Cheers,

Martin> Am 15.03.2015 um 02:37 schrieb Rintze Zelle <@Rintze_Zelle>:

7

Yeah, that’s a known issue:

8

Great job!

Joel

Rintze Zelle schreef op 15-3-2015 om 2:37:> Hi everybody,

9

looks good! thanks!