Minor visual issues in the documentation
Opened this issue ยท 17 comments
This issue is intended to serve as a place where minor visual issues regarding the documentation can be collected. Once enough such have been identified, they will be resolved in a corresponding PR.
Note in particular that this issue should not be used to collect major changes. Basically, if you see something in our documentation and think "Huh, that just looks a bit weird and would benefit from reformatting", then this is the place to just put it ๐
EDIT: The following issues have been identified:
- Cut-off in the table describing the numerical parameters:
- The caching outputs in the examples should all go.
- There are weird formatting jumps in some examples:
- Ugly table in light mode in search space userguide
- Bad cutoff of very long pages (see eg. in df_appl_permutation_augmentation)
- Alternative to
baybe
in the table of contents (NOTE: I do not think that this is possible, putting this here nevertheless) - Output/Warnings on console when building the documentation
- Reduce level of toc in User Guide overview page
- Improve visual of example plot on github README in dark mode
- Weird formatting in the docstring of the FPS sampling:
The following issues have already been fixed:
- Incorrect display of cardinality constraint in docstring (fixed in #405 )
This kind of formatting issue happns ons everal example pages, here for desirability:
In general, getting rid of progress bar outputs or at least just having one line (to show the user that somethign WAS computing) would be nice. The caching outputs should go alltogether.
Here in addition we have weird formatting jumps too:
@Scienfitz the tqdm
progress bars are already gone, which bars are you referring to?
@AVHopp thats right I thought I still saw progress bars somewhere but it seems theyre gone and I probably confused some of the cache notifications with them
@Scienfitz the
tqdm
progress bars are already gone, which bars are you referring to?
Would definitely be nice to have some indication of how far along the search is though!
Curious why this was removed?
@brandon-holt this Issue is just about the documentation, where progress bars have been removed. The progress bars when using our simulation module should still be there
@Scienfitz In the Simulation section, the section for simulate_experiment contains a codeblock for simulate scenarios:
https://emdgroup.github.io/baybe/userguide/simulation.html
Also, the codeblocks used don't make certain aspects of usage clear. For example, for the campaign variable, do we need to define a searchspace, or will the searchspace be automatically generated from initial_data?
Or, if we use the DataFrame option for the lookup variable, is that not the same dataframe as for initial_data?
@brandon-holt thanks for spotting that! technically your points are not visual but about a bug and content suggestions, so we should not discuss these in this thread.
Would you be open to make s small PR fixing the code snippet? The respective .md file is in docs/userguide/simulation.md
. You could also propose text changes that make clearer what you seek.
As for the searchspace question: Nothing is inferred from initial_data
, is there anything specific that gave you that impression?
@Scienfitz Just made the PR!
Also, disregard my question about searchspace/initial_data I understand now!
The "baybe" item in the sidebar should be replaced with a better name at some point.
See also: #329 (comment)
Since the question came up in #347 : Some of the errors mentioned here are fixed in #347 , some things I do not know how to fix (like changing the name of baybe
in the TOC, I already tried that several times).
Regarding the other things here: Depending on the urgency, I can take care of these in an upcoming PR and then close this issue and we start another one once we accumulate more stuff. What is your opinion here?