Mirrors/miller
1
0
Fork 0
mirror of https://github.com/johnkerl/miller.git synced 2026-01-23 02:14:13 +00:00
Code Issues Projects Releases Wiki Activity

Simplify release & dev build processes (#735)

Browse source
This commit is contained in:
John Kerl 2021-11-07 23:41:15 -05:00 • committed by GitHub
parent 91def6906f
commit 950337fde1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 64 additions and 91 deletions
Download patch file Download diff file Expand all files Collapse all files

22
Makefile
View file

@ -12,5 +12,25 @@ install:
make -C go install
make -C man install
# For developers before pushing to GitHub.
#
# These steps are done in a particular order:
# go:
# * builds the mlr executable
# man:
# * creates manpage mlr.1 and manpage.txt using mlr from the $PATH
# * copies the latter to docs/src
# docs:
# * turns *.md.in into *.md (live code samples), using mlr from the $PATH
# * note the man/manpage.txt becomes some of the HTML content
# * turns *.md into docs/site HTML and CSS files
precommit:
make -C go fmt
make -C go build
make -C go check
make -C man build
make -C docs
echo DONE
# Go does its own dependency management, outside of make.
.PHONY: build
.PHONY: build precommit

6
docs/Makefile Normal file
View file

@ -0,0 +1,6 @@
# Turn src/*.md.in into respective src/*.md. Then, generate static HTML into ./site.
build:
make -C src genmds
mkdocs build
.PHONY: build

13
docs/mkdocs-readme.md.not
View file

@ -16,19 +16,16 @@
* `docs/src` has `*.md.in` files containing markdown as well as directives for auto-generating code samples.
* A `genmds` script reads `docs/src/*.md.in` and writes `docs/src/*.md`.
* The `mkdocs build` tools reads `docs/src/*.md` and writes HTML files in `docs/site`.
* Running `make` within the `docs` directory handles both of those steps.
* Quick-editing loop:
* In one terminal, cd to this directory and leave `mkdocs serve` running.
* In another terminal, cd to the `src` subdirectory of `docs` and edit `*.md.in`.
* Run `genmds` to re-create all the `*.md` files, or `genmds foo.md.in` to just re-create the `foo.md.in` file you just edited.
* Run `genmds` to re-create all the `*.md` files, or `genmds foo.md.in` to just re-create the `foo.md.in` file you just edited, or (simplest) just `make` within the `docs/src` subdirectory.
* In your browser, visit http://127.0.0.1:8000
* This doesn't write HTML in `docs/site`; HTML is served up directly in the browser -- this is nice for previewing interactive edits
* This doesn't write HTML in `docs/site`; HTML is served up directly in the browser -- this is nice for previewing interactive edits.
* For-publish editing loop:
* Leave one terminal open as a place you will run `mkdocs build`
* In one terminal, cd to the `src` subdirectory of `docs` and edit `*.md.in`.
* Generate `src/*.md` from `src/*.md.in`, and then from that generate the `site/*/*.html`:
* Run `genmds` to re-create all the `*.md` files, or `genmds foo.md.in` to just re-create the `foo.md.in` file you just edited.
* In the first terminal, run `mkdocs build` which will populate the `site` directory.
* See also [./regen.sh](./regen.sh) which combines the `genmds` and `mkdocs build` steps.
* cd to the `src` subdirectory of `docs` and edit `*.md.in`.
* `make -C ..`
* This does write HTML in `docs/site`.
* In your browser, visit `file:///your/path/to/miller/docs/site/index.html`
* Link-checking:

31
docs/src/Makefile
View file

@ -1,28 +1,11 @@
# Minimal makefile for Sphinx documentation
#
# Note: run this after make in the ../c directory and make in the ../man directory
# since ../c/mlr is used to autogenerate ../man/manpage.txt which is used in this directory.
# See also https://miller.readthedocs.io/en/latest/build.html#creating-a-new-release-for-developers
# Miller docs have lots of text generated by running the Miller executable. We
# have source files named like foo.md.in which are writable; the ./genmds
# script turns each into its respective foo.md file.
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
FILES=$(wildcard *.md)
# Respective MANPATH entries would include /usr/local/share/man or $HOME/man.
INSTALLDIR=/usr/local/share/man/man1
INSTALLHOME=$(HOME)/man/man1
genmds: $(FILES)
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
%.md: %.md.in
@./genmds $<
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
./genmds
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

4
docs/src/build.md
View file

@ -69,8 +69,8 @@ In this example I am using version 6.1.0 to 6.2.0; of course that will change fo
* Update version found in `mlr --version` and `man mlr`:
* Edit `go/src/version/version.go` from `6.1.0-dev` to `6.2.0`.
* `sh build-go-src-test-man-doc.sh`
* The ordering in this script is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs.
* Run `make precommit` in the Miller repo base directory
* The ordering in this makefile rule is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs.
* Commit and push.
* Create the release tarball and SRPM:

4
docs/src/build.md.in
View file

@ -53,8 +53,8 @@ In this example I am using version 6.1.0 to 6.2.0; of course that will change fo
* Update version found in `mlr --version` and `man mlr`:
* Edit `go/src/version/version.go` from `6.1.0-dev` to `6.2.0`.
* `sh build-go-src-test-man-doc.sh`
* The ordering in this script is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs.
* Run `make precommit` in the Miller repo base directory
* The ordering in this makefile rule is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs.
* Commit and push.
* Create the release tarball and SRPM:

7
docs/src/contributing.md
View file

@ -48,7 +48,6 @@ PRs which pass regression test ([https://github.com/johnkerl/miller/blob/main/go
Much of Miller's documentation is autogenerated from code. With the `miller/go`
directory in your `$PATH` (so it will find the modified `mlr` executable if
you've modified any source code), please do `sh build-go-src-test-man-doc.sh`
in the `miller` directory. This runs source build, unit test, regression test,
manual-page autogen, document autogen, and document static-build all in the
correct order.
you've modified any source code), please do `make precommit` in the Miller base
directory. This runs source build, unit test, regression test, manual-page
autogen, document autogen, and document static-build all in the correct order.

7
docs/src/contributing.md.in
View file

@ -32,7 +32,6 @@ PRs which pass regression test ([https://github.com/johnkerl/miller/blob/main/go
Much of Miller's documentation is autogenerated from code. With the `miller/go`
directory in your `$PATH` (so it will find the modified `mlr` executable if
you've modified any source code), please do `sh build-go-src-test-man-doc.sh`
in the `miller` directory. This runs source build, unit test, regression test,
manual-page autogen, document autogen, and document static-build all in the
correct order.
you've modified any source code), please do `make precommit` in the Miller base
directory. This runs source build, unit test, regression test, manual-page
autogen, document autogen, and document static-build all in the correct order.

35
docs/src/make.bat
View file

@ -1,35 +0,0 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

2
docs/src/manpage.md
View file

@ -2975,5 +2975,5 @@ SEE ALSO
2021-11-06 MILLER(1)
2021-11-08 MILLER(1)
</pre>

2
docs/src/manpage.txt
View file

@ -2954,4 +2954,4 @@ SEE ALSO
2021-11-06 MILLER(1)
2021-11-08 MILLER(1)

8
go/src/cli/flag_types.go
View file

@ -107,10 +107,10 @@ type Flag struct {
// * Any code bits should be marked with backticks. These look OK for
// on-line help / manpage, and render marvelously for webdocs which
// take markdown.
// * After changing flags you can run `sh build-go-src-test-man-doc.sh`
// followed by `git diff` to see how the output looks. See also
// the README.md files in the docs and man directories for how
// to look at the autogenned docs pre-commit.
// * After changing flags you can run `make precommit` in the Miller
// repo base directory followed by `git diff` to see how the output
// looks. See also the README.md files in the docs and man directories
// for how to look at the autogenned docs pre-commit.
help string
// A function for parsing the command line, as described above.

2
go/src/input/record_reader_csv.go
View file

@ -23,7 +23,7 @@ type RecordReaderCSV struct {
// ----------------------------------------------------------------
func NewRecordReaderCSV(readerOptions *cli.TReaderOptions) (*RecordReaderCSV, error) {
if readerOptions.IRS != "\n" {
return nil, errors.New("CSV IRS can only be newline; LF vs CR/LF is autodetected.")
return nil, errors.New("CSV IRS cannot be altered; LF vs CR/LF is autodetected.")
}
if len(readerOptions.IFS) != 1 {
return nil, errors.New("CSV IFS can only be a single character")

6
go/src/output/record_writer_csv.go
View file

@ -13,6 +13,7 @@ import (
type RecordWriterCSV struct {
writerOptions *cli.TWriterOptions
ofs0 byte // Go's CSV library only lets its 'Comma' be a single character
csvWriter *csv.Writer
// For reporting schema changes: we print a newline and the new header
lastJoinedHeader *string
@ -21,8 +22,11 @@ type RecordWriterCSV struct {
}
func NewRecordWriterCSV(writerOptions *cli.TWriterOptions) (*RecordWriterCSV, error) {
if len(writerOptions.OFS) != 1 {
return nil, errors.New("CSV OFS can only be a single character")
}
if writerOptions.ORS != "\n" {
return nil, errors.New("CSV ORS can only be newline")
return nil, errors.New("CSV ORS cannot be altered")
}
return &RecordWriterCSV{
writerOptions: writerOptions,

2
man/manpage.txt
View file

@ -2954,4 +2954,4 @@ SEE ALSO
2021-11-06 MILLER(1)
2021-11-08 MILLER(1)

4
man/mlr.1
View file

@ -2,12 +2,12 @@
.\" Title: mlr
.\" Author: [see the "AUTHOR" section]
.\" Generator: ./mkman.rb
.\" Date: 2021-11-06
.\" Date: 2021-11-08
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
.TH "MILLER" "1" "2021-11-06" "\ \&" "\ \&"
.TH "MILLER" "1" "2021-11-08" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Portability definitions
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~