[doc] Streamline Drake build instructions #22461
Conversation
jwnimmer-tri
added
priority: medium
release notes: none
|
@drake-jenkins-bot linux-jammy-unprovisioned-clang-bazel-experimental-debug please |
jwnimmer-tri
changed the title
There was a problem hiding this comment.
Reviewable status: 3 unresolved discussions, needs platform reviewer assigned, needs at least two assigned reviewers
doc/_pages/from_source.md line 106 at r1 (raw file):
version is hard-coded in Drake and cannot be configured. * WITH_SNOPT (default OFF). When ON, enables the `SnoptSolver` in the build. * This option is mutally exclusive with `WITH_ROBOTLOMOTION_SNOPT`.
typo
Suggestion:
ROBOTLOCOMOTIONdoc/_pages/from_source.md line 112 at r1 (raw file):
* Drake does not support using a SNOPT binary release (i.e., shared library); it requires a source archive (i.e., the Fortran code). * WITH_ROBOTLOMOTION_SNOPT (default OFF). When ON, enables the `SnoptSolver`
typo
Suggestion:
ROBOTLOCOMOTIONdoc/_pages/from_source.md line 178 at r1 (raw file):
If you enable any of proprietary solvers flags, then you must first install the solver and set environment variables per the [Proprietary Solvers](http://127.0.0.1:8000/bazel.html#proprietary-solvers)
BTW: I'm not sure that this is going to be sane when viewed on the drake website? Consider a relative URL?
Suggestion:
bazel.html#proprietary-solvers
There is now a single install_prereqs script for all platforms, which defaults to installing only the build prereqs (not developer prereqs). (Future work will further consolidate the prereqs into simpler files.) Retool our from_source (user) and bazel (developer) pages to use the new script and generally rewrite large chunks for improved clarity.
jwnimmer-tri
force-pushed
the
doc-install-repave
branch
from
65ec436 to
b881cac
Compare
There was a problem hiding this comment.
Let me propose this:
+@sherm1 for feature review of the changes in setup/_pages/bazel.md (i.e., the developer-focused docs), please.
+@mwoehlke-kitware for feature review of the changes in setup/** plus the changes to docs/_pages/from_source.md, please.
Then for a final pass, we'll have 1 platform reviewer look over the whole thing including cross-checking all of the small 1-line edits.
WDYT?
Reviewable status: LGTM missing from assignees ggould-tri(platform),sherm1(platform),mwoehlke-kitware, labeled "do not merge" (waiting on @jwnimmer-tri)
There is now a single install_prereqs script for all platforms, which defaults to installing only the build prereqs (not developer prereqs). (Future work will further consolidate the implementation of the prereqs into simpler files.)
Retool our from_source (user) and bazel (developer) pages to use the new script and generally rewrite large chunks for improved clarity.
There are basically four main flows we focus on now:
(1) Typical users who install from binary (
installation.html).(2) Advanced users who need/decide to install from source (
from_source.html).(3) Drake developers/contributors (
bazel.html).(4) Downstream projects that already use Bazel (the small tail end of
from_source.html).The goal here is to make each of those four flows have a particular home in our docs, to have each of their flows be simple / easy / robust, and to redirect people who start from the wrong page (wrong flow) back into the flow they should be using.
This change is