Documentation checklist

[samukweku]

The aim here is to have a checklist of documentation suggestions, and also to keep track, in case others have suggestions or are already working on one, they can reference from here. Contributions/suggestions on what should be included as documentation are welcome.

Content

• pandas vs datatable syntax comparison #2679

• R data.table vs datatable syntax comparison #2611

• DOCS: list of features from R which are (not) available in python #2400

• SQL vs datatable syntax comparison #2665

• add examples to functions in docstrings; this will help users understand how to use the functions quickly,

• transformation documentation

  • Create a column/multiple columns
  • Mutate existing columns
  • Operation between columns
  • Apply function across columns (row-wise and column-wise)
  • Iteration through a frame
  • Sorting on a Frame
    - [ ] Aggregations (with and without groupby) - refer to by documentation
  • Datatable rules on column names during transformation
    - [ ] Combining columns/frames (rbind/cbind)
    - [ ] Comparing frames
  • Conditional transformations

• Selecting and Filtering data (i and j)

  • Selection by label/position/callable/type? (j)
  • notes/warnings on combining selection options
  • Filtering/selecting rows in the i section (position/callable/type?)
  • Drop rows/columns
  • Selecting with missing labels
  • Warning on use of python keywords for column names
  • Single value access
  • Boolean indexing
  • Bracket notation vs attribute selection with f?
  • Note on irrelevance of index labels?

• documentation on joins

  • Combining Frames horizontally and vertically (cbind/rbind)
  • Combining Frames in SQL-like manner (left join)
  • Limitations of SQL-like join
  • Comparing Frames

• string operations in datatable

• cookbook

• updates to existing documentation (e.g fread ... more information on fread and excel (named ranges, ...)

• iread examples how to use iread to read a list of csv #3353

• Document all functions in the API: API Documentation checklist #2586

Technical

• Documentation rendering issues #2605
• Improve style of doc page on R/Python comparison #2625
• Improve styling of code samples in the docs #2626
• Improve rendering of links in docs #2627
• Support extraction of docstrings from python #2628
• Documentation for .build_info didn't render on readthedocs #2633
• Update style of the documentation front page #2654

[st-pasha]

Hi Samuel,
thanks for taking up this initiative. As you probably noticed, we've spent a significant effort lately to improve our documentation. We're currently mostly focused on documenting the API (see #2586), but various tutorials / user guides might be just as useful if not more useful.
I've sent you an invite to join the project, so that you can create PRs directly (without going through the trouble of forking), and also better manage issues: assign labels, projects, milestones, etc.

[samukweku]

Yes, I noticed documentation on the API. I was particularly happy to see the guide on creating and adding a function to datatable. Thanks for the opportunity @st-pasha

[myamullaciencia]

Great Initiative @samukweku, I would choose one or two sections from the checklist and get back to yours here sooner. and i will let yours know if i need any help.

[samukweku]

@myamullaciencia cool! Will be on the lookout for your PR

[st-pasha]

Samuel, have you seen #2400 -- do you think it's something that can be incorporated inside your data.table/datatable comparison page?

[samukweku]

@st-pasha It is a good idea. I will make a PR to cover that.

[samukweku]

@st-pasha I noticed that datatable docs does not get updated when new docs are added. Same goes for the changelog. Any reasons for this? Maybe a design decision? I believe users (me included) would love to get access to new information.

[st-pasha]

I've set up a webhook just now, so hopefully it'll start building automatically now.

[samukweku]

@st-pasha No worries; I'll keep checking the site. At the moment, it has not updated.

[samukweku]

Website updates fine now

[samukweku]

• update transform documentation on extend - it covers more than just a dictionary.
• Add example to select documentation on columns with alias for renaming