mirror of
https://github.com/johnkerl/miller.git
synced 2026-01-23 02:14:13 +00:00
| .. | ||
| _static | ||
| data | ||
| multi-join | ||
| ngrams | ||
| pix | ||
| polyglot-dkvp-io | ||
| programs | ||
| .vimrc | ||
| 10-1.sh | ||
| 10-2.sh | ||
| 10min.rst | ||
| 10min.rst.in | ||
| build.rst | ||
| build.rst.in | ||
| circle.csv | ||
| commas.csv | ||
| conf.py | ||
| contact.rst | ||
| contact.rst.in | ||
| cookbook.rst | ||
| cookbook.rst.in | ||
| cookbook2.rst | ||
| cookbook2.rst.in | ||
| cookbook3.rst | ||
| cookbook3.rst.in | ||
| customization.rst | ||
| customization.rst.in | ||
| data-examples.rst | ||
| data-examples.rst.in | ||
| data-sharing.rst | ||
| data-sharing.rst.in | ||
| dates.csv | ||
| etymology.rst | ||
| etymology.rst.in | ||
| example.csv | ||
| expo-sample.sh | ||
| faq.rst | ||
| faq.rst.in | ||
| feature-comparison.rst | ||
| feature-comparison.rst.in | ||
| features.rst | ||
| features.rst.in | ||
| file-formats.rst | ||
| file-formats.rst.in | ||
| genrst | ||
| h1foo | ||
| h2foo | ||
| h2rfoo | ||
| h3foo | ||
| index.rst | ||
| install.rst | ||
| install.rst.in | ||
| internationalization.rst | ||
| internationalization.rst.in | ||
| log-processing-examples.rst | ||
| log-processing-examples.rst.in | ||
| log.txt | ||
| make.bat | ||
| Makefile | ||
| manpage.rst | ||
| manpage.rst.in | ||
| manpage.txt | ||
| mk-func-h2s.sh | ||
| mk-func-table.rb | ||
| mlr.1 | ||
| oosvar-example-ewma.sh | ||
| oosvar-example-sum-grouped.sh | ||
| oosvar-example-sum.sh | ||
| originality.rst | ||
| originality.rst.in | ||
| performance.rst | ||
| performance.rst.in | ||
| poki | ||
| pokifoo | ||
| quick-examples.rst | ||
| quick-examples.rst.in | ||
| README.md | ||
| record-heterogeneity.rst | ||
| record-heterogeneity.rst.in | ||
| reference-dsl.rst | ||
| reference-dsl.rst.in | ||
| reference-verbs.rst | ||
| reference-verbs.rst.in | ||
| reference.rst | ||
| reference.rst.in | ||
| release-docs.rst | ||
| release-docs.rst.in | ||
| sample_mlrrc | ||
| sql-examples.rst | ||
| sql-examples.rst.in | ||
| square.csv | ||
| triangle.csv | ||
| variance.mlr | ||
| verb-example-ewma.sh | ||
| why.rst | ||
| why.rst.in | ||
Miller Sphinx docs
Why use Sphinx
- Connects to https://miller.readthedocs.io so people can get their docmods onto the web instead of the self-hosted https://johnkerl.org/miller/doc. Thanks to @pabloab for the great advice!
- More standard look and feel -- lots of people use readthedocs for other things so this should feel familiar
- We get a Search feature for free
Contributing
- You need
pip install sphinx(orpip3 install sphinx) - The docs include lots of live code examples which will be invoked using
mlrwhich must be somewhere in your$PATH - Clone https://github.com/johnkerl/miller and cd into
docs/within your clone - Editing loop:
- Edit
*.rst.in - Run
make html - Either
open _build/html/index.html(MacOS) or point your browser tofile:///path/to/your/clone/of/miller/docs/_build/html/index.html
- Edit
- Submitting:
git addyour modified files,git commit,git push, and submit a PR at https://github.com/johnkerl/miller
- A nice markup reference: https://www.sphinx-doc.org/en/1.8/usage/restructuredtext/basics.html
Notes
- CSS:
- I used the Sphinx Classic theme which I like a lot except the colors -- it's a blue scheme and Miller has never been blue.
- Files are in
docs/_static/*.csswhere I marked my mods with/* CHANGE ME */. - If you modify the CSS you must run
make clean html(not justmake html) then reload in your browser.
- Live code:
- I didn't find a way to include non-Python live-code examples within Sphinx so I adapted the pre-Sphinx Miller-doc strategy which is to have a generator script read a template file (here,
foo.rst.in), run the marked lines, and generate the output file (foo.rst). - Edit the
*.rst.infiles, not*.rstdirectly. - Within the
*.rst.infiles are lines likePOKI_RUN_COMMAND. These will be run, and their output included, bymake htmlwhich calls thegenrstscript for you.
- I didn't find a way to include non-Python live-code examples within Sphinx so I adapted the pre-Sphinx Miller-doc strategy which is to have a generator script read a template file (here,
- readthedocs:
To do
- Let's all discuss if/how we want the v2 docs to be structured better than the v1 docs.