[jira] [Commented] (SPARK-19551) Theme for PySpark documenation could do with improving
[ https://issues.apache.org/jira/browse/SPARK-19551?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15945685#comment-15945685 ] Arthur Tacca commented on SPARK-19551: -- Thanks, I needed the reminder! In fact the person that generated their own build of the docs got back to me; I hope they don't mind me pasting what they said here: I've compiled the documentation using Sphinx (ver 1.3.5.). I have a foggy memory on this as it's been a while, but I recall I had to rollback to older version of sphinx to have copybutton.js to work properly - this is what allows us to toggle the ``>>>`` mark in the python code - (example) http://takwatanabe.me/pyspark/generated/generated/mllib.classification.DenseVector.html#mllib.classification.DenseVector - (js file) https://github.com/scipy/scipy-sphinx-theme/blob/master/_theme/scipy/static/js/copybutton.js Otherwise, I simply just used the ``autosummary`` directive offered by Sphinx (http://www.sphinx-doc.org/en/stable/ext/autosummary.html). You can see how I used these in the *.rst files in https://github.com/wtak23/pyspark/tree/master/source. For instance, in order to create the **entire** html subtrees from the link http://takwatanabe.me/pyspark/pyspark.ml.html , all I had to have was this rst file: https://raw.githubusercontent.com/wtak23/pyspark/master/source/pyspark.ml.rst Once you have PySpark directory included in your $PYTHONPATH envvar, you should be able to simply run ``make html`` using the Makefile from the github branch below. https://github.com/wtak23/pyspark/tree/master > Theme for PySpark documenation could do with improving > -- > > Key: SPARK-19551 > URL: https://issues.apache.org/jira/browse/SPARK-19551 > Project: Spark > Issue Type: Documentation > Components: Documentation, PySpark >Affects Versions: 2.1.0 >Reporter: Arthur Tacca >Priority: Minor > > I have found the Python Spark documentation hard to navigate for two reasons: > * Each page in the documentation is huge, because the whole of the > documentation is split up into only a few chunks. > * The methods for each class is not listed in a short form, so the only way > to look through them is to browse past the full documentation for all methods > (including parameter lists, examples, etc.). > This has irritated someone enough that they have done [their own build of the > pyspark documentation|http://takwatanabe.me/pyspark/index.html]. In > comparison to the official docs they are a delight to use. But of course it > is not clear whether they'll be kept up to date, which is why I'm asking here > that the official docs are improved. Perhaps that site could be used as > inspiration? I don't know much about these things, but it appears that the > main change they have made is to switch to the "read the docs" theme. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: issues-unsubscr...@spark.apache.org For additional commands, e-mail: issues-h...@spark.apache.org
[jira] [Commented] (SPARK-19551) Theme for PySpark documenation could do with improving
[ https://issues.apache.org/jira/browse/SPARK-19551?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15943211#comment-15943211 ] Hyukjin Kwon commented on SPARK-19551: -- [~arthur-tacca], I am just curious about this. Do you have any news on this maybe? > Theme for PySpark documenation could do with improving > -- > > Key: SPARK-19551 > URL: https://issues.apache.org/jira/browse/SPARK-19551 > Project: Spark > Issue Type: Documentation > Components: Documentation, PySpark >Affects Versions: 2.1.0 >Reporter: Arthur Tacca >Priority: Minor > > I have found the Python Spark documentation hard to navigate for two reasons: > * Each page in the documentation is huge, because the whole of the > documentation is split up into only a few chunks. > * The methods for each class is not listed in a short form, so the only way > to look through them is to browse past the full documentation for all methods > (including parameter lists, examples, etc.). > This has irritated someone enough that they have done [their own build of the > pyspark documentation|http://takwatanabe.me/pyspark/index.html]. In > comparison to the official docs they are a delight to use. But of course it > is not clear whether they'll be kept up to date, which is why I'm asking here > that the official docs are improved. Perhaps that site could be used as > inspiration? I don't know much about these things, but it appears that the > main change they have made is to switch to the "read the docs" theme. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: issues-unsubscr...@spark.apache.org For additional commands, e-mail: issues-h...@spark.apache.org
[jira] [Commented] (SPARK-19551) Theme for PySpark documenation could do with improving
[ https://issues.apache.org/jira/browse/SPARK-19551?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15873771#comment-15873771 ] Arthur Tacca commented on SPARK-19551: -- Sorry, I thought that it would be enough to use the Read the Docs theme, but I was wrong. Switching to that theme is really easy, but I tried it myself and found that it only changed the colors and style. The main change in the docs I linked to is that things are broken up into smaller pages, and classes all have a compact table of methods. I'm not sure what was done to make that happen, so I contacted the person that generated them and asked what he did. I'll let you know if he gets back to me. > Theme for PySpark documenation could do with improving > -- > > Key: SPARK-19551 > URL: https://issues.apache.org/jira/browse/SPARK-19551 > Project: Spark > Issue Type: Documentation > Components: Documentation, PySpark >Affects Versions: 2.1.0 >Reporter: Arthur Tacca >Priority: Minor > > I have found the Python Spark documentation hard to navigate for two reasons: > * Each page in the documentation is huge, because the whole of the > documentation is split up into only a few chunks. > * The methods for each class is not listed in a short form, so the only way > to look through them is to browse past the full documentation for all methods > (including parameter lists, examples, etc.). > This has irritated someone enough that they have done [their own build of the > pyspark documentation|http://takwatanabe.me/pyspark/index.html]. In > comparison to the official docs they are a delight to use. But of course it > is not clear whether they'll be kept up to date, which is why I'm asking here > that the official docs are improved. Perhaps that site could be used as > inspiration? I don't know much about these things, but it appears that the > main change they have made is to switch to the "read the docs" theme. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: issues-unsubscr...@spark.apache.org For additional commands, e-mail: issues-h...@spark.apache.org
[jira] [Commented] (SPARK-19551) Theme for PySpark documenation could do with improving
[ https://issues.apache.org/jira/browse/SPARK-19551?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15871475#comment-15871475 ] Sean Owen commented on SPARK-19551: --- Ping [~arthur-tacca] If this is a doc build config change, that's easy, but, what's the change? If you mean someone should write a whole framework for doc themes, no I don't think that's in scope for Spark. > Theme for PySpark documenation could do with improving > -- > > Key: SPARK-19551 > URL: https://issues.apache.org/jira/browse/SPARK-19551 > Project: Spark > Issue Type: Documentation > Components: Documentation, PySpark >Affects Versions: 2.1.0 >Reporter: Arthur Tacca >Priority: Minor > > I have found the Python Spark documentation hard to navigate for two reasons: > * Each page in the documentation is huge, because the whole of the > documentation is split up into only a few chunks. > * The methods for each class is not listed in a short form, so the only way > to look through them is to browse past the full documentation for all methods > (including parameter lists, examples, etc.). > This has irritated someone enough that they have done [their own build of the > pyspark documentation|http://takwatanabe.me/pyspark/index.html]. In > comparison to the official docs they are a delight to use. But of course it > is not clear whether they'll be kept up to date, which is why I'm asking here > that the official docs are improved. Perhaps that site could be used as > inspiration? I don't know much about these things, but it appears that the > main change they have made is to switch to the "read the docs" theme. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: issues-unsubscr...@spark.apache.org For additional commands, e-mail: issues-h...@spark.apache.org
[jira] [Commented] (SPARK-19551) Theme for PySpark documenation could do with improving
[ https://issues.apache.org/jira/browse/SPARK-19551?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15861522#comment-15861522 ] Sean Owen commented on SPARK-19551: --- How do you apply the theme? I don't think it's something specific to Spark nor something Spark would custom build. If it's easy to flip some switches though, that's great. > Theme for PySpark documenation could do with improving > -- > > Key: SPARK-19551 > URL: https://issues.apache.org/jira/browse/SPARK-19551 > Project: Spark > Issue Type: Documentation > Components: Documentation, PySpark >Affects Versions: 2.1.0 >Reporter: Arthur Tacca >Priority: Minor > > I have found the Python Spark documentation hard to navigate for two reasons: > * Each page in the documentation is huge, because the whole of the > documentation is split up into only a few chunks. > * The methods for each class is not listed in a short form, so the only way > to look through them is to browse past the full documentation for all methods > (including parameter lists, examples, etc.). > This has irritated someone enough that they have done [their own build of the > pyspark documentation|http://takwatanabe.me/pyspark/index.html]. In > comparison to the official docs they are a delight to use. But of course it > is not clear whether they'll be kept up to date, which is why I'm asking here > that the official docs are improved. Perhaps that site could be used as > inspiration? I don't know much about these things, but it appears that the > main change they have made is to switch to the "read the docs" theme. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: issues-unsubscr...@spark.apache.org For additional commands, e-mail: issues-h...@spark.apache.org
