#general
- r
rough-minister-58256
08/07/2015, 5:52 PM - r
rough-minister-58256
08/07/2015, 5:52 PMwasn’t pants on rtd at some point? - r
rough-minister-58256
08/07/2015, 5:55 PM(is sphinx based) - r
rough-minister-58256
08/07/2015, 5:55 PMah, looks like you can run your own RTD site - r
rough-minister-58256
08/07/2015, 5:55 PM - a
astonishing-jelly-60479
08/07/2015, 5:56 PMi think sphinx autodoc would be useful for API documentation on internals - r
rough-minister-58256
08/07/2015, 5:56 PMunclear if we have infra for that, perhaps easiest to just use the public rtd instance - a
ancient-stone-50795
08/07/2015, 6:02 PMI just got back from lunch. I’ll do the release now - b
billowy-alarm-80641
08/07/2015, 6:04 PMI think that Larry understands the doc stuff the best -- would be worth an email to him to see why he went from .rst -> .md - b
billowy-alarm-80641
08/07/2015, 6:04 PMbut I recall him being pretty passionate about it being the right thing to do - r
rough-minister-58256
08/07/2015, 6:05 PMyou wanna shoot him a quick mail? - a
ancient-stone-50795
08/07/2015, 6:05 PMIIRC, the reason was mainly that people didn’t understand .rst very well and were reluctant to change the docs. Markdown was considered a more least-common-denomiator so that developers would be more inclined to contribute docs. - b
billowy-alarm-80641
08/07/2015, 6:05 PMsure - e
enough-analyst-54434
08/07/2015, 6:10 PMI'm biased here, but with that idea in mind (I seem to recall the same now that you mention it) - it would be highly ironic to switch to .rst to - in the end - make the sight prettier and reverse Larry's goal of getting more substance from more people. Yes pretty docs would be good, but I can't imagine this is so at the expense of good docs. - b
bored-art-40741
08/07/2015, 6:11 PMI think that's a false dichotomy - e
enough-analyst-54434
08/07/2015, 6:12 PMIt may be - but we all bitch about docs alot and basically contribute none - b
bored-art-40741
08/07/2015, 6:12 PMYup, md or rst, this is how docs work in basically all software - b
bored-art-40741
08/07/2015, 6:12 PMNo one wants to write them, it takes effort to get any contribution at all - b
bored-art-40741
08/07/2015, 6:12 PMI think that's orthogonal to the prettiness - b
bored-art-40741
08/07/2015, 6:13 PMTo me, using the most standard possible python doc system is the best way to get well documented (ha) processes that we can look to other projects for reference, and to get pretty, community maintained css - e
enough-analyst-54434
08/07/2015, 6:13 PMI guess my only point is Larry contributed 95% of docs, was/is a tech writer and so his opinion/evidence probably has more weight than ours - b
bored-art-40741
08/07/2015, 6:13 PMWe are already so nonstandard in so many of our toolchain choices that another non-standard choice really adds to the burden - b
billowy-alarm-80641
08/07/2015, 6:14 PMemail sent - h
happy-kitchen-89482
08/07/2015, 6:15 PMwell, the non-generated, manually-written doc content may need a lot of updating now anyway? - h
happy-kitchen-89482
08/07/2015, 6:15 PMI'd defer to larry's judgement though - h
happy-kitchen-89482
08/07/2015, 6:16 PMon why we made that switch - h
happy-kitchen-89482
08/07/2015, 6:16 PMwe can probably hack together some css that makes it look the way we want - b
bored-art-40741
08/07/2015, 6:16 PMThat's much easier said than done - a
astonishing-jelly-60479
08/07/2015, 6:16 PMas a relative newcomer, i think the point about the current approach being nonstandard is a valid one - b
bored-art-40741
08/07/2015, 6:16 PMEspecially when you consider mobile support