docs: categories - #2898

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.62%. Comparing base (5da6dff) to head (e230647).
⚠️ Report is 50 commits behind head on main.

@@            Coverage Diff             @@
##             main    #2898      +/-   ##
==========================================
+ Coverage   75.51%   75.62%   +0.11%     
==========================================
  Files         406      406              
  Lines       75347    75772     +425     
  Branches    15054    15228     +174     
==========================================
+ Hits        56899    57304     +405     
- Misses      18448    18468      +20     

My current thinking on the R side is that igraph.r2cdocs should also take care of _pkgdown.yml, so roxygenize() would update the reference index configuration.

Re igraph.r2cdocs: Let's carefully evaluate the pros and cons of hosting this in a separate repo.

I've been thinking about this since we've spoken, and again, I am not too keen on doing too much with this categorization, or creating an extra maintenance burden by requiring that these need to be kept up-to-date.

These categories are simply not that meaningful, and very subjective. I've just implemented a function to check if a graph is triangle free. Where does that fit? Structural properties? Transitivity? Motifs (where some triangle functions are)? It really is useful for graph theory, not network science, so should we have a category for that?

It feels like putting a lot of effort into formalizing something that is far from being properly fleshed out, and far from ready to be set in stone.

You said that you'd prefer to use this to break up rinterface.c and aaa-auto.R into several files. The usual motivation for breaking up source files is maintainability. But these files are auto-generated, so their size has no impact on maintainability. In fact, there is an advantage to keeping all auto-generated code together to make it easier to search.

I see that this is generated with an R script. There are two possibilities here: 1. The file is initially generated, then manually kept up to date. This is extra burden that I am not in favour of. 2. The file is always generated. I absolutely do not want to add a dependence on R for the C/igraph build system.

Given that this information is auto-generated with an R script, and is intended to be used in R/igraph, I think this should go into the R/igraph system (i.e. not this repository).

What is your take on this @ntamas ? The relevant issue is #2889

To summarize the objections: 1. If manually maintained, this is extra burden. 2. This repo should have no R dependence. 3. Not currently useful for C/igraph, and the categorization is not well-founded.

@krlmlr first 10 words of what?

I'll explore a bit more then we can discuss where to put that if we want to keep using those categories for the R scripts and pkgdown config.

@szhorvat I think part of the idea is that R/aaa-auto.R is so big that it's not nice to open and that it makes AI read too much, but I might be mistaken.

For docs, it's fine if a function is in several categories, or only one, because site-wide search and cross-references from similar functions should help navigation.

For scripts (and in R, we align test files with code files), the splitting might not be perfect but it's better than nothing.

An automatic approach might be imperfect but it's ok. Now, it's true that in the R case, we already made a lot of efforts to create the pkgdown config.

Reporting back. Generating part of the pkgdown reference config from the categories would work but some R functions are pure R so we'd need to decide on categories for those anyway. igraph/igraph.r2cdocs#9

Random thought: should the top-level category be the scientific field (physics, social sciences, graph theory, general-purpose graph algorithms)? It's fine if a function lives in multiple categories anyway.

Let's discuss separately where this lives and how it is maintained.

should the top-level category be the scientific field (physics, social sciences, graph theory, general-purpose graph algorithms)?

No, that will not work well here.

It's fine if a function lives in multiple categories anyway.

OK, let's do this so that multiple categories are allowed, which makes things a lot easier (there can be a main one if necessary). Would it be easier if subcategories are not used?

Random thought: should the top-level category be the scientific field (physics, social sciences, graph theory, general-purpose graph algorithms)? It's fine if a function lives in multiple categories anyway.

@krlmlr this sounds like an idea for a @family in the R igraph package docs.