Some bike shed questions comments welcomed 1 What do we call

Question

Some bike shed questions comments welcomed 1 What do we call the goal to generate docs `docs` `docsgen` `docs gen` `gen docs` 2 Where do we write the result `dist docs lt project name gt `

hundreds-father-404 · Answer

< ancient vegetable 10556> and I both believe it s valuable to have a dedicated goal for docs rather than using `export codegen` and `package` It s not quite codegen You iterate on docs much more than packaging binaries Making it easy to distinguish those makes sense to me for Marketing tm we want to make clear Pants will soon support docs

high-yak-85899 · Answer

I like `gen docs` because it follows how I would say generate documentation and all the other goals have an actionable take to them `run` `test` `format` etc

wide-midnight-78598 · Answer

` pants docs ` Keeps the simplicity vibe going with the rest of the goals But it s not a verb which kinda sucks Hyphens in goals are a bit annoying to type and see

wide-midnight-78598 · Answer

`package` is half reasonable but it feels as right as it feels wrong

hundreds-father-404 · Answer

I think it being a verb is a good idea I like `gen docs` Note we already have the hyphen like `export codegen`

wide-midnight-78598 · Answer

Yeah I don t like export codegen either slightly smiling face

witty-crayon-22786 · Answer

i d still vote for `package` probably for the reasons in <https pantsbuild slack com archives C046T6T9U p1649178458914749 thread ts=1649176870 827779 amp cid=C046T6T9U>

witty-crayon-22786 · Answer

and because i think that it should work with the `publish` goal

flat-zoo-31952 · Answer

`document` since it s a verb

hundreds-father-404 · Answer

ohhh that s a good point about `publish` gt You iterate on docs much more than packaging binaries Making it easy to distinguish those makes sense to me Actually this is pretty contrived You iterate on one docsite at a time So just use ` pants package path to project` rather than ` ` gt for Marketing tm we want to make clear Pants will soon support docs also not a compelling reason for a whole new goal There are other ways of marketing this

wide-midnight-78598 · Answer

Maybe default to `package` and extract to a new goal if a compelling reason comes down the pipeline Not sure if that s easily automatically updatable

hundreds-father-404 · Answer

Alright I m convinced with `package` which answers both questions slightly smiling face Feel free anyone to argue in favor of a docs goal tho It is very helpful for us to due diligence now

wide-midnight-78598 · Answer

Almost reaching a full screen of goals on my desktop monitor slightly smiling face

hundreds-father-404 · Answer

gt Almost reaching a full screen of goals on my desktop monitor slightly smiling face Yeah true Proliferation of goals can be an issue More APIs for you as a user to learn

wide-midnight-78598 · Answer

Yep a couple more and it pushes me off screen

witty-crayon-22786 · Answer

Eric has a proposal to maybe merge 4 5 of those into 2 crossed fingers

hundreds-father-404 · Answer

sort of just `tailor` and `update build files` And then Benjy has proposed merging `export` and `export codegen`

hundreds-father-404 · Answer

and Benjy has proposed getting rid of advanced options so just `help` and `help all`

proud-dentist-22844 · Answer

so doing ` pants package docs ` might invoke sphinx if the right target is in place

hundreds-father-404 · Answer

yep exactly a `sphinx project` target which has default `sources= conf py rst ` Markdown Myst support is my next task

proud-dentist-22844 · Answer

I guess that works and makes sense `package` feels odd at first but grows on me and I can get used to it

proud-dentist-22844 · Answer

So would the `sphinx project` target define the output directory under `dist `

hundreds-father-404 · Answer

It works tada ``` pants package sphinx demo 18 15 32 12 INFO Wrote dist sphinx demo sphinx``` Just gotta write some tests and Pants will support Sphinx hopefully in a few hours

proud-dentist-22844 · Answer

tada

hundreds-father-404 · Answer

`output path` field like all binary targets Defaults to `path to build file dir tgt name` But you can override it It will set the directory path

hundreds-father-404 · Answer

Ohhhh `package` goal integration is neat because you can do things like for tests the `runtime package dependencies` field Pants will build your docs for you and you can use them in your test

witty-crayon-22786 · Answer

or put them in an `archive` or

hundreds-father-404 · Answer

will get this landable after dinner but damn is the engine powerful 22 lines of ` rule` logic < happy kitchen 89482> you ll like this PR

wide-midnight-78598 · Answer

Does sphinx or docformatter handle ` md` files

high-yak-85899 · Answer

Sphinx can

high-yak-85899 · Answer

There s an extension `recommonmark` I think

wide-midnight-78598 · Answer

I always have PrettierJS installed so that s what I end up using by default in VS Code