new docs, complete #3369

lazarusA · 2023-08-11T20:59:48Z

This updates de current docs template.

Feature missing: versioning, to be addressed on a different PR, if this is proposal is good enough.

This is how it looks like, once the site is build:

light

dark

bkamins · 2023-08-12T21:08:23Z

Thank you! I will ping the community on Slack for the feedback.

My question would be how the width of the middle section scales as the window is resized horizontally? (also how the new template behaves on mobile). Maybe some reference docs that use a similar template can be x-linked so that users can play with it?

Now we have something like:

which is not optimal.

lazarusA · 2023-08-13T08:24:36Z

The template is responsive on all devices. Usually we should have a (link) preview per PR but I don't see one for this PR (it looks like external PRs don't get deployed).

Similar templates are:

https://juliadatacubes.github.io/YAXArrays.jl/dev/
https://tidierorg.github.io/TidierData.jl/latest/
https://rafaqz.github.io/DimensionalData.jl/dev/

and also some loca previews for some devices:

bkamins · 2023-08-13T08:46:46Z

Feature missing: versioning, to be addressed on a different PR

This can be a separate PR, but I just wanted to make sure how it would work. In particular - we will have old docs in a different format and new docs in a new format. Would these integrate or not?

lazarusA · 2023-08-13T09:09:34Z

the way it is now links to old docs will not be integrated. However, once versioning is working the idea is to have them integrated, as in

https://www.evetion.nl/SpaceLiDAR.jl/dev/

although, at the moment I still haven't figured out the right workflow to achieve this.

bkamins · 2023-08-13T09:16:05Z

maybe just adding a link to old docs somewhere would suffice? Thank you for working on it.

lazarusA · 2023-08-13T09:31:13Z

Yes, a link will be the easiest solution. Maybe another badge linking the old docs, to version 1.6 I suppose. https://dataframes.juliadata.org/v1.6/

bkamins · 2023-08-13T11:11:57Z

.gitignore

 Manifest.toml
 .DS_Store
 .vscode
+
+/Manifest.toml


Manifest.toml (also below) and .vscode are duplicate.
We do not use deps, tmp, generated and build AFAICT. Why do you add them?

tmp so that my local tmp attempts don't get committed, deps should go

generated is also generated in local builds, and build should go also I think.

bkamins · 2023-08-13T11:13:56Z

.github/workflows/Documenter.yml

+          JULIA_DEBUG: "Documenter"
+          DATADEPS_ALWAYS_ACCEPT: true
+        run: |
+          julia --code-coverage=user --project=docs/ --color=yes docs/make.jl


why add --code-coverage=user? This is the default, right? Is it used for anything in this build?

Is it used for anything in this build?
nope. It should go.

docs/make.jl

bkamins · 2023-08-13T11:15:52Z

docs/make.jl

-    ],
-    strict = true
+    clean=true,
+    doctest=false,


why do you set doctest=false?

some tests were failing on main, and in order to build the initial site I set this to false. I agree that it should be true but my concern was not about fixing those issues and rather having the template up.

bkamins · 2023-08-13T11:17:11Z

docs/make.jl

+    clean=true,
+    doctest=false,
+    sitename="DataFrames.jl",
+    authors="Bogumił Kamiński et al.",


@lazarusA - thank you for putting this 😄, but we need some wider agreement on the authors. @nalimilan - what do you think we should have here? Maybe JuliaData et at. (or indeed putting some names?)

bkamins · 2023-08-13T11:17:57Z

docs/make.jl

+        :linkcheck,
+        :parse_error,
+        :example_block,
+        # Other available options are


while we are at it I would try to turn on as many checks as possible (and if some fail try fixing this, unless for some reason it is not possible)

if any of them fail, building the docs is not possible. That's why I set the test one to false.

bkamins · 2023-08-13T11:19:29Z

docs/mkdocs.yml

+theme:
+  name: material
+  logo: assets/logo.png
+  features:


are there any of the features that are debatable (i.e. that it would be worth to decide if we turn them on/off - there are many of them and for most I do not understand in 100% what they do 😄)?

I only use the ones that make sense to me 😄 . And I left the others just in case someone wants to play with these settings.

bkamins · 2023-08-13T11:20:34Z

docs/mkdocs.yml

+    - "Functions": "./lib/functions.md"
+    - "Indexing": "./lib/indexing.md"
+    - "Metadata": "./lib/metadata.md"
+#    hide("Internals" => "lib/internals.md")


why hide is not needed any more? I would assume that Documenter.jl would error if we do not cover this file in docs with hide.

as it is, it just outputs a warning saying that this is file is available but not in the menu bar.

lalonso@pc DataFrames.jl % cd docs lalonso@pc docs % mkdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: - assets/README.md - lib/internals.md INFO - Documentation built in 2.54 seconds INFO - [13:44:20] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [13:44:20] Serving on http://127.0.0.1:8000/

bkamins · 2023-08-13T11:22:13Z

docs/src/index.md


-This resource aims to teach you everything you need to know to get up and
-running with tabular data manipulation using the DataFrames.jl package.
+Welcome to the `DataFrames.jl `documentation!


why backquote DataFrames.jl here and below? This is not code. We consistently use package names in plain text in the docs/docstrings in DataFrames.jl.

ok. If that's the convention, it should be like that. For me these ones here are just a guide to the eye. I will fix this.

bkamins · 2023-08-13T11:23:06Z

docs/src/index.md

@@ -64,8 +76,8 @@ a list of well-supported libraries that provide different data science tools,
 along with a few notes about what makes each library special, and how well
 integrated they are with DataFrames.jl.

-
- **Statistics**
+```@raw html


why this triplebackquote with @raw html is needed?

what does ??? tip command do?

raw and ??? are to have an expandable menu.

bkamins · 2023-08-13T11:23:41Z

docs/src/javascripts/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {


This is very good! We avoided LaTeX in the docs, but now we can use it.

bkamins · 2023-08-13T11:24:23Z

I left some comments/questions as probably I do not know everything I should know 😄. Thank you!

lazarusA · 2023-08-13T11:47:53Z

this is the output for raw and ???

Co-authored-by: Bogumił Kamiński <bkamins@sgh.waw.pl>

lazarusA · 2023-08-13T12:44:23Z

thanks for the feedback, latest commit should address them. Except authorship 😄 .
Thanks for taking the time to review.

digital-carver · 2023-08-14T12:20:14Z

Looking at TidierData docs, the font sizes of text inside the expandable ??? sections seem to be several sizes smaller than the text of the rest of the page, making them harder to read. (Same goes for the "Top-level macros" and "Helper functions" admonition-sections in the second half of that page.) Will that be the case here too, and is there any way to avoid that font size reduction?

bkamins · 2023-08-14T14:21:33Z

I have checked this both on laptop and on mobile and they are readable. Having said that indeed they are several sizes smaller. @lazarusA - maybe making them only a bit smaller than the main text would be better?
(I assume making them smaller is intentional)

lazarusA · 2023-08-14T17:42:02Z

@bkamins yes, being smaller is intentional and is the default, but now with the latest commit we can change it if we want. I increased the fontsize a little bit, now is just 1px below the main text. IMO now is big/distinguishable enough.

bkamins · 2023-08-16T11:15:21Z

@lazarusA - we have reviewed and discussed this PR internally. The short conclusion is the following:

we believe that look&feel you propose is better than what we have; so this is a plus 😄
at the same time we want to make sure that we will not run into issues with long term maintenance of the documentation (note that for this package we really need to think in 10-years ahead mode); so this is a minus 😞

The concrete potential problems we see are:

PR introduces DocumenterMarkdown.jl dependency, and this package documentation states that it is not actively maintained; last patch release was 2 years ago.
PR introduces dependencies on Python and multiple Python packages; it is not clear for us if there is a guarantee that these packages would be actively maintained in the long-term and that the integration would keep working.
No one of the core contributors knows the newly introduced ecosystem (we know how to build and deploy docs with Documenter.jl only); this means that we would need information on several potential maintainers of this part of the package, if we merged the PR, so that if something stops working in the future there is someone with the understanding how things work and how to fix them.
It was not fully clear to us if the new template supports forward-versioning (we understand it does not support backward versioning, but does it support switching versions for the future releases); also, in particular, since current versioning relies on URL e.g. https://dataframes.juliadata.org/v1.3/ for latest patch release of 1.3 version it was not fully clear why it cannot be supported out of the box (it seems that general versioning would just switch to the old version of the documentation).

@lazarusA could you please comment on how you see these issues? I know you have put a lot of effort into this PR, however, we need to be sure that merging it will not run into technical issues that will outweigh the benefits of better display.

lazarusA · 2023-08-16T11:49:40Z

could you please comment

I will not. Thanks for taking the time. I, don't have more time to get into a back and forth discussion.

bkamins · 2023-08-16T14:31:57Z

Thank you for working on the PR.

new docs, complete

9638fd8

bkamins added the doc label Aug 12, 2023

bkamins added this to the 1.7 milestone Aug 12, 2023

adds badge to old docs, v1.6

fe12757

bkamins requested a review from nalimilan August 13, 2023 11:08

bkamins reviewed Aug 13, 2023

View reviewed changes

docs/make.jl Outdated Show resolved Hide resolved

bkamins reviewed Aug 13, 2023

View reviewed changes

lazarusA and others added 2 commits August 13, 2023 13:48

Update docs/make.jl

07128c3

Co-authored-by: Bogumił Kamiński <bkamins@sgh.waw.pl>

up ignore, tests to true, rm sticks, up make

ed2fbec

control fontsize in admonition

bb0d5a2

lazarusA closed this Aug 16, 2023

lazarusA deleted the docs_proposal branch August 16, 2023 11:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

new docs, complete #3369

new docs, complete #3369

lazarusA commented Aug 11, 2023

bkamins commented Aug 12, 2023 •

edited

Loading

lazarusA commented Aug 13, 2023

bkamins commented Aug 13, 2023

lazarusA commented Aug 13, 2023

bkamins commented Aug 13, 2023

lazarusA commented Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

lazarusA Aug 13, 2023

bkamins Aug 13, 2023

bkamins commented Aug 13, 2023

lazarusA commented Aug 13, 2023

lazarusA commented Aug 13, 2023

digital-carver commented Aug 14, 2023

bkamins commented Aug 14, 2023

lazarusA commented Aug 14, 2023

bkamins commented Aug 16, 2023

lazarusA commented Aug 16, 2023

bkamins commented Aug 16, 2023

new docs, complete #3369

new docs, complete #3369

Conversation

lazarusA commented Aug 11, 2023

light

dark

bkamins commented Aug 12, 2023 • edited Loading

lazarusA commented Aug 13, 2023

bkamins commented Aug 13, 2023

lazarusA commented Aug 13, 2023

bkamins commented Aug 13, 2023

lazarusA commented Aug 13, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bkamins commented Aug 13, 2023

lazarusA commented Aug 13, 2023

lazarusA commented Aug 13, 2023

digital-carver commented Aug 14, 2023

bkamins commented Aug 14, 2023

lazarusA commented Aug 14, 2023

bkamins commented Aug 16, 2023

lazarusA commented Aug 16, 2023

bkamins commented Aug 16, 2023

bkamins commented Aug 12, 2023 •

edited

Loading