#general
- b
bored-art-40741
08/07/2015, 6:41 PMI agree - a
astonishing-jelly-60479
08/07/2015, 6:43 PMi'm trying to push sphinx internally here so i'm willing to invest some time at least in terms of investigation/a spike for pants... things like finding out how easy it would be to set up readthedocs, automate conversion from .md to .rst, set up autodoc - a
astonishing-jelly-60479
08/07/2015, 6:44 PMbut i'm just a user in the peanut gallery so to speak - h
happy-kitchen-89482
08/07/2015, 6:56 PMI agree with advocates for something doing the thing, but there has to be discussion first... - h
happy-kitchen-89482
08/07/2015, 6:56 PMWhich is what this is, I hope. - h
happy-kitchen-89482
08/07/2015, 6:57 PMI'm agnostic on sphinx vs. markdown because I don't know enough about either. - h
happy-kitchen-89482
08/07/2015, 6:57 PMBut I think "ease of prettification", "standardization" and "ease of writing" are all valid criteria, some of which favor one and some the other. - h
happy-kitchen-89482
08/07/2015, 6:59 PMCould we push more of the documentation into docstrings, and then grab it from there to put into generated .md or .rst or whatever? - h
happy-kitchen-89482
08/07/2015, 6:59 PMOr is there too much formatting? - h
happy-kitchen-89482
08/07/2015, 6:59 PME.g., could a "how to set up an artifact cache" page live in the docstring for artifact cache code? - h
happy-kitchen-89482
08/07/2015, 6:59 PMJust spitballing. - a
astonishing-jelly-60479
08/07/2015, 7:01 PMyou could probably put it in a module-level docstring, but for a "how to" it might just make sense to put it in its own file - a
astonishing-jelly-60479
08/07/2015, 7:02 PMsphinx would give you the ability to cross-reference that how-to to specific parts of the internals, for which there might be autogenerated documentation - a
ancient-stone-50795
08/07/2015, 7:04 PMLarry floats switching to Markdown with the group: https://groups.google.com/forum/#!searchin/pants-devel/markdown/pants-devel/fKA1ETjglrM/1loT9n65N-cJ Design doc: https://docs.google.com/a/twitter.com/document/d/1zDW7kNMXz1b4Cy2KG6hnNArfF85Aid87ad5y-hj9u1E - a
ancient-stone-50795
08/07/2015, 7:06 PMIf you are volunteering to switch from md back to rst, you can take a look at the work that might be required to make this happen by perusing Larry’s PR’s: https://rbcommons.com/s/twitter/users/lahosken/?page=2 One thing’s for sure. Switching to .rst will not get us a website that looks like: https://buckbuild.com/ - a
ancient-stone-50795
08/07/2015, 7:06 PM - a
ancient-stone-50795
08/07/2015, 7:07 PMTo do that, we need to have someone manually design a site, and then figure out how to plugin our content. - a
ancient-stone-50795
08/07/2015, 7:08 PMRead the docs is great for documenting a library: https://pex.readthedocs.org/en/latest/ - a
ancient-stone-50795
08/07/2015, 7:09 PMBut is it really going to give us the kind of website that folks want to go to for all of the many roles they may have (contributor, user, administrator, evaluator)? - h
happy-kitchen-89482
08/07/2015, 7:12 PM=@zundel - h
happy-kitchen-89482
08/07/2015, 7:12 PMthat's why I was hoping to get some UX/UI resources - h
happy-kitchen-89482
08/07/2015, 7:12 PMSo we can build a real site, and have generated content be just a part of it. - b
bored-art-40741
08/07/2015, 7:13 PMTo answer your last question, @ancient-stone-50795, I think yes - b
bored-art-40741
08/07/2015, 7:13 PMYou can have arbitrary sections and subsections of content on a readthedocs site - b
bored-art-40741
08/07/2015, 7:14 PMThose can be used to divide up tutorial, example, library doc, and administrivia sections - b
bored-art-40741
08/07/2015, 7:14 PMIndeed I think your link to the pex docs demonstrates that nicely - a
ancient-stone-50795
08/07/2015, 7:16 PM@bored-art-40741: I think that https://docs.readthedocs.org is probably the best case for what we will get. What you can get are sites with a table of contents on the left and content on the right. - a
ancient-stone-50795
08/07/2015, 7:17 PMIs this the kind of site we really want? - b
bored-art-40741
08/07/2015, 7:18 PMIt's standard, it's better than what we have now, and it doesn't take a large amount of upfront and then ongoing effort to maintain it - r
rough-minister-58256
08/07/2015, 7:19 PMisnt that pretty much the exact same layout we have right now?