google / google/or-tools

cp_model python docs are bad

Open
#5,216 5 comments 0 reactions 1 assignee Claimed by @Mizux View on GitHub
Doc: Optimization Site Lang: Python
Dominant language
C++
Stars
14.1k
Forks
2.5k
Avg merge
8h 39m
Merged PRs (30d)
72

Description

https://or-tools.github.io/docs/pdoc/ortools/sat/python/cp_model.html

- Many broken links: ".CpModel", ".CpSolver", "..CpSolverSolutionCallback", ".ObjectiveSolutionPrinter", ".VarArraySolutionPrinter", #boundedlinearexpression (all lower case), etc.
- Definitions add nothing: "class BoundedLinearExpression" = "A class to hold a linear expression with bounds." ; "def add_all_different(self, *expressions)" = "Adds AllDifferent(expressions)."
- Argument definitions try to be precise but are wrong. E.g. add_all_different: "*expressions: simple expressions of the form a * var + constant." But actually it accepts multi-variable sums, presumably any LinearExpr. So why not say that?
- only_enforce_if: same documentation is repeated 4 times
- Too much syntax, not enough examples. I shouldn't have to understand the internal workings of LinearExpr before I can use model.add_all_different, for instance.
- The table of contents on the left-hand side is useless because it is too long. Table of contents for the old docs had function names for CpModel and CpSolver, and only the class name for everything else.
- Many classes and methods are not documented: How to use search_strategy? How to use symmetry? If the solver returns MODEL_INVALID, how do I diagnose? When does it return OPTIMAL vs FEASIBLE?
- Smooth scrolling is annoying. Yes, it is possible to disable it within Edge flags, but why should I have to?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.