# Migrating documentation to docs.citationstyles.org

**URL:** <https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238>\
**Category:** CSL Development\
**Created:** [October 22, 2014, 6:31pm UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238 "2014-10-22T18:31:57Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [October 22, 2014, 6:31pm UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/1 "2014-10-22T18:31:57Z")

</div>

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](https://github.com/rmzelle/writing), with the rendered  
documentation available at [docs.citationstyles.org](http://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/](http://citationstyles.org/downloads/)… to [docs.citationstyles.org](http://docs.citationstyles.org). This  
would affect the CSL specification, primer, and release notes. Unless  
people suggest otherwise, I’m planning to:

- move the existing source files at [https://github.com/rmzelle/writing](https://github.com/rmzelle/writing)  
to [https://github.com/citation-style-language/documentation](https://github.com/citation-style-language/documentation).
- adapt the existing source files at  
[https://github.com/citation-style-language/documentation](https://github.com/citation-style-language/documentation) for rendering  
through Read the Docs.

This move would have several advantages:

- [http://citationstyles.org/downloads/specification.html](http://citationstyles.org/downloads/specification.html) is currently  
generated with [https://bitbucket.org/fbennett/rst4csl](https://bitbucket.org/fbennett/rst4csl), a custom Python  
script Frank wrote. So far, I always had to run the script locally,  
and upload the generated HTML to [citationstyles.org](http://citationstyles.org) by hand. In  
contrast, Read the Docs offers GitHub integration, so documentation is  
automatically regenerated after every commit.
- the “/downloads/” path was always a bit weird.  
[http://docs.citationstyles.org/](http://docs.citationstyles.org/)… is much nicer.
- Read the Docs has support for GitHub branches, so we could offer  
rendered versions for each CSL release, and the master development  
branch. The main drawback is that we’re stuck with long URLs like  
[http://docs.citationstyles.org/en/latest/primer.html](http://docs.citationstyles.org/en/latest/primer.html). The alternative  
is giving up branch support, which would shorten the URLs to  
[http://docs.citationstyles.org/primer.html](http://docs.citationstyles.org/primer.html) (see  
[https://docs.readthedocs.org/en/latest/single\_version.html](https://docs.readthedocs.org/en/latest/single_version.html)).

Best,

Rintze

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [October 22, 2014, 6:34pm UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/2 "2014-10-22T18:34:41Z")

</div>

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

Rintze

---

<div class="post-metadata">

**Author:** ![Aurimas\_Vinckevicius](https://avatars.discourse-cdn.com/v4/letter/a/e47774/32.png) [@Aurimas\_Vinckevicius](https://discourse.citationstyles.org/u/Aurimas_Vinckevicius)\
**Post date:** [October 22, 2014, 6:46pm UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/3 "2014-10-22T18:46:05Z")

</div>

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](http://httpd.apache.org/docs/current/mod/mod_rewrite.html)

Aurimas

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [October 28, 2014, 1:26am UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/4 "2014-10-28T01:26:03Z")

</div>

So, any opinions on how to best organize our CSL documentation?  
[http://docs.citationstyles.org/en/latest/](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](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](https://github.com/citation-style-language/documentation), so we end up  
with something like:

[http://docs.citationstyles.org/en/stable/](http://docs.citationstyles.org/en/stable/) (default for users visiting  
[http://docs.citationstyles.org/;](http://docs.citationstyles.org/;) mirrors content of latest release)  
[http://docs.citationstyles.org/en/master/](http://docs.citationstyles.org/en/master/) (for development)  
[http://docs.citationstyles.org/en/1.0.1/](http://docs.citationstyles.org/en/1.0.1/) (for CSL 1.0.1)  
[http://docs.citationstyles.org/en/1.0/](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](http://read-the-docs.readthedocs.org/en/latest/versions.html) and  
[http://semver.org/](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

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [March 15, 2015, 1:37am UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/5 "2015-03-15T01:37:21Z")

</div>

Hi everybody,

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

[http://docs.citationstyles.org/](http://docs.citationstyles.org/) had existed for a while, but was populated  
from [https://github.com/rmzelle/writing](https://github.com/rmzelle/writing). I now updated  
[https://github.com/citation-style-language/documentation/](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/](http://docs.citationstyles.org/). We now have:

[http://docs.citationstyles.org/en/stable/](http://docs.citationstyles.org/en/stable/)  
[http://docs.citationstyles.org/en/1.0.1/](http://docs.citationstyles.org/en/1.0.1/)  
[http://docs.citationstyles.org/en/1.0/](http://docs.citationstyles.org/en/1.0/)  
[http://docs.citationstyles.org/en/1.0-20100321/](http://docs.citationstyles.org/en/1.0-20100321/)  
[http://docs.citationstyles.org/en/master/](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](http://citationstyles.org/downloads/pages) (e.g.,  
[http://citationstyles.org/downloads/specification.html](http://citationstyles.org/downloads/specification.html) redirects to  
[http://docs.citationstyles.org/en/stable/specification.html](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

---

<div class="post-metadata">

**Author:** ![Martin\_Fenner1](https://avatars.discourse-cdn.com/v4/letter/m/8491ac/32.png) [@Martin\_Fenner1](https://discourse.citationstyles.org/u/Martin_Fenner1)\
**Post date:** [March 15, 2015, 11:13am UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/6 "2015-03-15T11:13:02Z")

</div>

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\>:

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [March 15, 2015, 1:45pm UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/7 "2015-03-15T13:45:51Z")

</div>

Yeah, that’s a known issue:

> <https://github.com/readthedocs/readthedocs.org/issues/1062>
>
> Hi.
> The "edit on github" link does not work for the stable documentation version, as it tries to open the non- existent...

---

<div class="post-metadata">

**Author:** ![Joel\_Hendriks](https://avatars.discourse-cdn.com/v4/letter/j/8edcca/32.png) [@Joel\_Hendriks](https://discourse.citationstyles.org/u/Joel_Hendriks)\
**Post date:** [March 15, 2015, 3:33pm UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/8 "2015-03-15T15:33:16Z")

</div>

Great job!

Joel

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

---

<div class="post-metadata">

**Author:** ![Carles\_Pina](https://avatars.discourse-cdn.com/v4/letter/c/dbc845/32.png) [@Carles\_Pina](https://discourse.citationstyles.org/u/Carles_Pina)\
**Post date:** [March 16, 2015, 11:51am UTC](https://discourse.citationstyles.org/t/migrating-documentation-to-docs-citationstyles-org/1238/9 "2015-03-16T11:51:57Z")

</div>

looks good! thanks!