Migrating documentation to docs.citationstyles.org

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Migrating documentation to docs.citationstyles.org

rmzelle
Administrator
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:

- move the existing source files at https://github.com/rmzelle/writing
to https://github.com/citation-style-language/documentation.
- adapt the existing source files at
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 is currently
generated with 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 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/... 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. The alternative
is giving up branch support, which would shorten the URLs to
http://docs.citationstyles.org/primer.html (see
https://docs.readthedocs.org/en/latest/single_version.html).

Best,

Rintze

------------------------------------------------------------------------------
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

rmzelle
Administrator
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

On Wed, Oct 22, 2014 at 2:31 PM, Rintze Zelle <[hidden email]> wrote:
> Unless
> people suggest otherwise, I'm planning to:
>
> - move the existing source files at https://github.com/rmzelle/writing
> to https://github.com/citation-style-language/documentation.
> - adapt the existing source files at
> https://github.com/citation-style-language/documentation for rendering
> through Read the Docs.

------------------------------------------------------------------------------
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

aurimas

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

On Oct 22, 2014 1:35 PM, "Rintze Zelle" <[hidden email]> wrote:
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

On Wed, Oct 22, 2014 at 2:31 PM, Rintze Zelle <[hidden email]> wrote:
> Unless
> people suggest otherwise, I'm planning to:
>
> - move the existing source files at https://github.com/rmzelle/writing
> to https://github.com/citation-style-language/documentation.
> - adapt the existing source files at
> https://github.com/citation-style-language/documentation for rendering
> through Read the Docs.

------------------------------------------------------------------------------
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel

------------------------------------------------------------------------------

_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

rmzelle
Administrator
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

------------------------------------------------------------------------------
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

rmzelle
Administrator
"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

On Mon, Oct 27, 2014 at 9:26 PM, Rintze Zelle <[hidden email]> wrote:
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


------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

Martin Fenner-2
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 <[hidden email]>:

"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

On Mon, Oct 27, 2014 at 9:26 PM, Rintze Zelle <[hidden email]> wrote:
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

------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel


------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

rmzelle
Administrator
Yeah, that's a known issue: https://github.com/rtfd/readthedocs.org/issues/1062

On Sun, Mar 15, 2015 at 7:13 AM, Martin Fenner <[hidden email]> wrote:
One small issue: the „Edit on Github“ links for the „stable“ version are broken, probably because there is no „stable“ git branch or tag.

------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

Joël Hendriks
In reply to this post by rmzelle
Great job!


Joel

Rintze Zelle schreef op 15-3-2015 om 2:37:

> 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
>
> On Mon, Oct 27, 2014 at 9:26 PM, Rintze Zelle <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     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
>
>
>
>
> ------------------------------------------------------------------------------
> Dive into the World of Parallel Programming The Go Parallel Website, sponsored
> by Intel and developed in partnership with Slashdot Media, is your hub for all
> things parallel software development, from weekly thought leadership blogs to
> news, videos, case studies, tutorials and more. Take a look and join the
> conversation now. http://goparallel.sourceforge.net/
>
>
>
> _______________________________________________
> xbiblio-devel mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
>

------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
Reply | Threaded
Open this post in threaded view
|

Re: Migrating documentation to docs.citationstyles.org

Carles Pina
In reply to this post by rmzelle
looks good! thanks!

On 15 March 2015 at 01:37, Rintze Zelle <[hidden email]> wrote:

> 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
>
> On Mon, Oct 27, 2014 at 9:26 PM, Rintze Zelle <[hidden email]>
> wrote:
>>
>> 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
>
>
>
> ------------------------------------------------------------------------------
> Dive into the World of Parallel Programming The Go Parallel Website,
> sponsored
> by Intel and developed in partnership with Slashdot Media, is your hub for
> all
> things parallel software development, from weekly thought leadership blogs
> to
> news, videos, case studies, tutorials and more. Take a look and join the
> conversation now. http://goparallel.sourceforge.net/
> _______________________________________________
> xbiblio-devel mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
>



--
Carles Pina | Software Engineer
http://www.mendeley.com/profiles/Carles-Pina/

Mendeley Limited | London, UK | www.mendeley.com
Registered in England and Wales | Company Number 6419015

------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
xbiblio-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/xbiblio-devel