https://pantsbuild.org/ logo
Join Slack
Powered by
Some bike shed questions, comments welcomed! 1. W...
# general
h
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/<project_name>
?
✅ 1
👍 2
@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™️, we want to make clear Pants will soon support docs
h
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.)
➕ 2
w
./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
package
is half reasonable, but it feels as right as it feels wrong
h
I think it being a verb is a good idea. I like 
gen-docs
Note we already have the hyphen like 
export-codegen
w
Yeah I don't like export-codegen either 🙂
👍 1
🤣 1
w
and because i think that it should work with the 
publish
goal
➕ 3
f
document
? since it's a verb
h
ohhh that's a good point about 
publish
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 
::
for Marketing™️, 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
w
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
➕ 1
h
Alright I'm convinced with 
package
, which answers both questions 🙂 Feel free anyone to argue in favor of a docs goal tho! It is very helpful for us to due diligence now
w
Almost reaching a full screen of goals on my desktop monitor 🙂
➕ 1
h
Almost reaching a full screen of goals on my desktop monitor 🙂
Yeah true. Proliferation of goals can be an issue. More APIs for you as a user to learn
w
Yep - a couple more and it pushes me off screen.
❗ 1
w
Eric has a proposal to maybe merge 4/5 of those (into 2?)… 🤞
➕ 1
h
sort of, just 
tailor
and 
update-build-files
. And then Benjy has proposed merging 
export
and 
export-codegen
and Benjy has proposed getting rid of "advanced options", so just 
help
and 
help-all
💯 1
p
so, doing 
./pants package docs/
might invoke sphinx, if the right target is in place?
h
yep, exactly: a 
sphinx_project
target, which has default 
sources=["conf.py", "**/*.rst"]
(Markdown/Myst support is my next task)
p
I guess that works and makes sense. 
package
feels odd at first, but grows on me and I can get used to it.
👍 1
So, would the 
sphinx_project
target define the output directory under 
dist/
?
h
It works 🎉
Copy code
❯ ./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
💃 1
p
🎉
h
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
👍 1
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
w
or put them in an 
archive
, or…
💯 1
h
will get this landable after dinner, but damn is the engine powerful. 22 lines of 
@rule
logic: https://github.com/pantsbuild/pants/pull/15512 @happy-kitchen-89482 you'll like this PR
🎉 2
w
Does sphinx or docformatter handle 
.md
files?
h
Sphinx can
💥 1
There's an extension (
recommonmark
I think)
w
I always have PrettierJS installed, so that's what I end up using by default in VS Code
7 Views
Open in Slack
PreviousNext
Powered by