From 069c0beff9f343eea75989e74571e1add8a5bccd Mon Sep 17 00:00:00 2001 From: John Kerl Date: Thu, 17 Jun 2021 00:28:32 -0400 Subject: [PATCH] Docs: Contributing --- docs6/contributing.rst | 30 ++++++++++++++++++++++++---- docs6/contributing.rst.in | 30 ++++++++++++++++++++++++---- docs6/reference-main-env-vars.rst | 17 +++------------- docs6/reference-main-env-vars.rst.in | 17 +++------------- go/todo.txt | 5 ++--- 5 files changed, 60 insertions(+), 39 deletions(-) diff --git a/docs6/contributing.rst b/docs6/contributing.rst index 9c5b5d11f..836423ac3 100644 --- a/docs6/contributing.rst +++ b/docs6/contributing.rst @@ -7,19 +7,41 @@ How to contribute Community ---------------------------------------------------------------- -TODO +You can ask questions -- or answer them! -- following the links at :doc:`community`. Documentation improvements ---------------------------------------------------------------- -TODO +Pre-release Miller documentation is at https://github.com/johnkerl/miller/tree/main/docs6. + +Clone https://github.com/johnkerl/miller and `cd` into `docs6`. + +After ``sudo pip install sphinx`` (or ``pip3``) you should be able to do ``make html``. + +Edit ``*.rst.in`` files, then ``make html`` to generate ``*.rst``, then run the Sphinx document-generator. + +Open ``_build/html/index.html`` in your browser, e.g. ``file:////Users/yourname/git/miller/docs6/_build/html/contributing.html``, to verify. + +PRs are welcome at https://github.com/johnkerl/miller. + +Once PRs are merged, readthedocs creates https://miller.readthedocs.io using the following configs: + +* https://readthedocs.org/projects/miller/ +* https://readthedocs.org/projects/miller/builds/ +* https://github.com/johnkerl/miller/settings/hooks Testing ---------------------------------------------------------------- -TODO +As of Miller-6's current pre-release status, the best way to test is to either build from source via :doc:`build`, or by getting a recent binary at https://github.com/johnkerl/miller/actions, then click latest build, then *Artifacts*. Then simply use Miller for whatever you do, and create an issue at https://github.com/johnkerl/miller/issues. + +Do note that as of 2021-06-17 a few things have not been ported to Miller 6 -- most notably, including regex captures and localtime DSL functions. Feature development ---------------------------------------------------------------- -TODO +Issues: https://github.com/johnkerl/miller/issues + +Developer notes: https://github.com/johnkerl/miller/blob/main/go/README.md + +PRs which pass regression test (https://github.com/johnkerl/miller/blob/main/go/regtest/README.md) are always welcome! diff --git a/docs6/contributing.rst.in b/docs6/contributing.rst.in index 12480ee8a..61632b5ab 100644 --- a/docs6/contributing.rst.in +++ b/docs6/contributing.rst.in @@ -4,19 +4,41 @@ How to contribute Community ---------------------------------------------------------------- -TODO +You can ask questions -- or answer them! -- following the links at :doc:`community`. Documentation improvements ---------------------------------------------------------------- -TODO +Pre-release Miller documentation is at https://github.com/johnkerl/miller/tree/main/docs6. + +Clone https://github.com/johnkerl/miller and `cd` into `docs6`. + +After ``sudo pip install sphinx`` (or ``pip3``) you should be able to do ``make html``. + +Edit ``*.rst.in`` files, then ``make html`` to generate ``*.rst``, then run the Sphinx document-generator. + +Open ``_build/html/index.html`` in your browser, e.g. ``file:////Users/yourname/git/miller/docs6/_build/html/contributing.html``, to verify. + +PRs are welcome at https://github.com/johnkerl/miller. + +Once PRs are merged, readthedocs creates https://miller.readthedocs.io using the following configs: + +* https://readthedocs.org/projects/miller/ +* https://readthedocs.org/projects/miller/builds/ +* https://github.com/johnkerl/miller/settings/hooks Testing ---------------------------------------------------------------- -TODO +As of Miller-6's current pre-release status, the best way to test is to either build from source via :doc:`build`, or by getting a recent binary at https://github.com/johnkerl/miller/actions, then click latest build, then *Artifacts*. Then simply use Miller for whatever you do, and create an issue at https://github.com/johnkerl/miller/issues. + +Do note that as of 2021-06-17 a few things have not been ported to Miller 6 -- most notably, including regex captures and localtime DSL functions. Feature development ---------------------------------------------------------------- -TODO +Issues: https://github.com/johnkerl/miller/issues + +Developer notes: https://github.com/johnkerl/miller/blob/main/go/README.md + +PRs which pass regression test (https://github.com/johnkerl/miller/blob/main/go/regtest/README.md) are always welcome! diff --git a/docs6/reference-main-env-vars.rst b/docs6/reference-main-env-vars.rst index 0bd769e23..a49bc35b1 100644 --- a/docs6/reference-main-env-vars.rst +++ b/docs6/reference-main-env-vars.rst @@ -4,18 +4,7 @@ Reference: Miller environment variables ================================================================ -TODO +* ``MLRRC``: see :doc:`customization` +* ``MLR_NO_COLOR``, ``MLR_ALWAYS_COLOR``, ``MLR_KEY_COLOR``, ``MLR_VALUE_COLOR``, ``MLR_PASS_COLOR``, ``MLR_FAIL_COLOR``, ``MLR_HELP_COLOR``, ``TERM``, * ``MSYSTEM``: see :doc:`output-colorization` +* ``MLR_REPL_PS1``, ``MLR_REPL_PS2``: see :doc:`repl` -* ``MLRRC`` -* ``HOME`` -* ``MLR_NO_COLOR`` -* ``MLR_ALWAYS_COLOR`` -* ``MLR_KEY_COLOR`` -* ``MLR_VALUE_COLOR`` -* ``MLR_PASS_COLOR`` -* ``MLR_FAIL_COLOR`` -* ``MLR_HELP_COLOR`` -* ``TERM`` -* ``MSYSTEM`` -* ``MLR_REPL_PS1`` -* ``MLR_REPL_PS2`` diff --git a/docs6/reference-main-env-vars.rst.in b/docs6/reference-main-env-vars.rst.in index 5479d5bed..670395428 100644 --- a/docs6/reference-main-env-vars.rst.in +++ b/docs6/reference-main-env-vars.rst.in @@ -1,18 +1,7 @@ Reference: Miller environment variables ================================================================ -TODO +* ``MLRRC``: see :doc:`customization` +* ``MLR_NO_COLOR``, ``MLR_ALWAYS_COLOR``, ``MLR_KEY_COLOR``, ``MLR_VALUE_COLOR``, ``MLR_PASS_COLOR``, ``MLR_FAIL_COLOR``, ``MLR_HELP_COLOR``, ``TERM``, * ``MSYSTEM``: see :doc:`output-colorization` +* ``MLR_REPL_PS1``, ``MLR_REPL_PS2``: see :doc:`repl` -* ``MLRRC`` -* ``HOME`` -* ``MLR_NO_COLOR`` -* ``MLR_ALWAYS_COLOR`` -* ``MLR_KEY_COLOR`` -* ``MLR_VALUE_COLOR`` -* ``MLR_PASS_COLOR`` -* ``MLR_FAIL_COLOR`` -* ``MLR_HELP_COLOR`` -* ``TERM`` -* ``MSYSTEM`` -* ``MLR_REPL_PS1`` -* ``MLR_REPL_PS2`` diff --git a/go/todo.txt b/go/todo.txt index aaccef9af..57f01bc27 100644 --- a/go/todo.txt +++ b/go/todo.txt @@ -31,9 +31,6 @@ DOC6 ? or q-e more links to 10min ! fill out: - o how-to-help guide - o repl guide - o env-vars section o new-in-miller-6: flatten/unflatten o JSON flatten/unflatten section o Arrays section including 1-up and why @@ -135,6 +132,8 @@ w survey NUMERICS < BOOL < VOID < STRING ================================================================ +* non-blocker: 'true && false' windows CLI-parse: debug + * non-blocker: commenting passes ... * non-blocker: new functions: