Why is new Selenium doc on html and not rst

Tarun K

unread,

Jul 26, 2016, 8:35:24 AM7/26/16

to Selenium Developers

I had posted this question on one pull request for doc but did not receive any response. Given that doc authors / devs also hang around on this forum, probably I get better insight.

I am a little perplexed with how a doc author has to deal with html encoding when writing code example in html. This may not be encouraging for first time doc committers.

Given that old sel doc are written using rst, it was easier for one to contribute without worrying about encoding.

What do others think of it?

Tarun K

unread,

Jul 26, 2016, 8:42:40 AM7/26/16

to Selenium Developers

came across this - http://stackoverflow.com/questions/15075332/viewing-rst-within-a-github-pages-site

Was it one reason to stick to html doc? Does not it sacrifice ease of writing doc?

Luke Inman-Semerau

unread,

Jul 26, 2016, 10:01:28 AM7/26/16

to selenium-...@googlegroups.com

I think rst is horrible! ;) and welcome the move away from it. I read what andreas wrote on the PR and agree that using flat HTML is probably best. Thankfully most of our examples will be written in programming languages where there is very little use of HTML entities.

Also I would like to note that in the 'old' seleniumhq page that contained the maven downloads is riddled with html escaping -

https://github.com/SeleniumHQ/www.seleniumhq.org/blob/master/src/main/webapp/download/maven.jsp

On Tue, Jul 26, 2016 at 5:42 AM, Tarun K <tku...@gmail.com> wrote:

came across this - http://stackoverflow.com/questions/15075332/viewing-rst-within-a-github-pages-site

Was it one reason to stick to html doc? Does not it sacrifice ease of writing doc?

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to selenium-develo...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/84895da1-2380-4c5a-9486-a146afc88adb%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

Santiago Suarez Ordoñez

unread,

Jul 26, 2016, 3:24:27 PM7/26/16

to selenium-...@googlegroups.com

I don't think RST is horrible, but agree that moving away from it was the right choice now that markdown has taken over the world.

As the original creator of the original ReStructuredText and Sphinx-based setup, I lead towards Tarun's opinion that the nuisance of HTML tags and the unlimited swath of formatting styles available with it is a roadblock when all you care about is making simple content contributions.

On the other hand, I'm not able to contribute to docs these days and Andreas has not only done a great job taking over and keeping docs rolling well past the days of the docs team but also been very receptive to anyone willing to help out and change things around if needed. Tarun, maybe it's a matter of coordinating with Andreas and figuring out if you're willing to help out enough to be worth moving the content over?

To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/CAL97Zu5BsyDFx%2B1arubVFJ_qx83phFJDQQx1oYLYAAdRfPBZ7w%40mail.gmail.com.

Paul Grandjean

unread,

Jul 28, 2016, 12:21:18 PM7/28/16

to Selenium Developers

Hey, it's great to see you guys are still involved with the docs!

I'm hoping to get the time to start following the dev list again after a long absence. Great to see you guys are still around. :-)

Paul

On Tuesday, July 26, 2016 at 12:24:27 PM UTC-7, Santiago Suarez Ordoñez wrote:

I don't think RST is horrible, but agree that moving away from it was the right choice now that markdown has taken over the world.

As the original creator of the original ReStructuredText and Sphinx-based setup, I lead towards Tarun's opinion that the nuisance of HTML tags and the unlimited swath of formatting styles available with it is a roadblock when all you care about is making simple content contributions.

On the other hand, I'm not able to contribute to docs these days and Andreas has not only done a great job taking over and keeping docs rolling well past the days of the docs team but also been very receptive to anyone willing to help out and change things around if needed. Tarun, maybe it's a matter of coordinating with Andreas and figuring out if you're willing to help out enough to be worth moving the content over?

On Tue, Jul 26, 2016 at 7:01 AM Luke Inman-Semerau <luke.s...@gmail.com> wrote:

I think rst is horrible! ;) and welcome the move away from it. I read what andreas wrote on the PR and agree that using flat HTML is probably best. Thankfully most of our examples will be written in programming languages where there is very little use of HTML entities.

Also I would like to note that in the 'old' seleniumhq page that contained the maven downloads is riddled with html escaping -
https://github.com/SeleniumHQ/www.seleniumhq.org/blob/master/src/main/webapp/download/maven.jsp

On Tue, Jul 26, 2016 at 5:42 AM, Tarun K <tku...@gmail.com> wrote:

came across this - http://stackoverflow.com/questions/15075332/viewing-rst-within-a-github-pages-site

Was it one reason to stick to html doc? Does not it sacrifice ease of writing doc?

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to selenium-developers+unsub...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/84895da1-2380-4c5a-9486-a146afc88adb%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to selenium-developers+unsub...@googlegroups.com.

Reply all

Reply to author

Forward