Searchable docs

hi guys,

So here’s the hardest thing for me when I started using igraph: I couldn’t find online, searchable docs.

So I ended up (still do, ahem!) downloading the PDF every time because at least I can Ctrl+F the function name I’m looking for.

Anyone with the same issue out there? If so we should fix this by 1.0

Cheers,
Faboi

Yes, this issue was already raised before, see Add sitewide search to igraph.org. Indeed, the lack of a proper search function is quite annoying. Having that properly implemented will definitely make it a lot easier for people to start coding with igraph.

What about for now adding a link to an html equivalent of the PDF (i.e. a single page with everything)? That would be relatively easy and we could use Ctrl+F there :wink:

Are you aware of the index? https://igraph.org/c/doc/ix01.html All functions are listed there, along with a short description.

Thank you, that’s better than nothing. I’ll try to see if we can get a single html page anyway, because one often needs the reverse search: from some functionality keyword to the function name

Would a custom Google search be a suitable quick workaround until we can set up a proper search for igraph.org?

I never used this before. I suspect it’s the same as using a normal google search and adding something like site:igraph.org or site:igraph.org/c at the end.

1 Like

Would be a great initial move for sure!

It turns out that we have already started setting this up a while ago; here is the URL:

https://cse.google.com/cse?cx=006731217555358536053:butkee157vc

Please give it a go to see whether it’s useful for searching the documentation; if it is, I’ll try to figure out how to integrate this nicely. Currently the search engine is indexing the entire igraph.org domain.

@iosonofabio This is related too: https://github.com/igraph/igraph/issues/1381 Dash is a popular offline doc browser for macOS. While the free version has built-in annoyances, I still find it useful and would be nice to add igraph to it. On Linux/Windows, Zeal is a free and compatible alternative.

@tamas great to see. Would be a great improvement to search separately for each interface (C/Python/R). Otherwise I almost always drown in a sea of irrelevant results. Is that easy to do?

@szhorvat I saw the issue before but since I’m not a OSX user I can’t really push this much. Never used zeal and, I suspect, never will. But if you use it a lot you could consider that a low-priority thing?

@iosonofabio I think it is possible to create independent search engines that index only a subset of the site (based on URL patterns), so yeah, this should work.

Here is a URL that is limited to igraph.org/c/doc:

https://cse.google.com/cse?cx=003494361702844740117:dlnifinshhm

To add to the confusion, I just ran into an old readthedocs about python-igraph: https://python-igraph.readthedocs.io/en/latest/. Perhaps it would be best to take this down in order to avoid confusion? I believe it is hosted by @tamas or @Gabor. Or we could actually use it, but in that case it would need to be updated. So still probably best to take it down, at least for now.

Most users will probably use documentation online, so I think that is more important than offline local documentation, such as Dash or other variants.

Let’s take it down but keep the namespace. Python folks will be quite familiar with readthedocs, and it’s searchable. I’ve set up several of those in the past, so let me have a look

1 Like

FYI: https://github.com/igraph/igraph/pull/1437

Removed the Python interface from readthedocs.io because apparently their build process cannot handle building arbitrary C extensions, and we need to build the C extension because some of the docstrings come directly from there.

As for the C documentation - each page of the manual now includes a search bar at the top of the page, roughly based on @iosonofabio’s original PR, but rewritten so the styling fits better with the rest of the page. Let me know if you run into any issues with it.

Fantastic work! The new search bar looks great!

We should add some mobile aware CSS block for it, else it looks broken on my phone.

Screenshot_20200713-075137|281x500

Also, why does searching for IGRAPH_OTHER give no results?

We should add some mobile aware CSS block for it,

Yeah, definitely; my intention was to make sure we don’t waste space with the search bar so it is floated to the left while the “prev / home / next” controls are floated to the right. This does not work on mobile phones, though. I’ll try to do this in the next few days; however, feel free to send a PR to igraph/igraph.org on Github.

Also, why does searching for IGRAPH_OTHER give no results?

Ask Google :wink: I believe it is because IGRAPH_OTHER is not documented in 0.8.2, and the homepage builds the docs from the 0.8.2 tag.

Sounds good, as expected. I’ll try and help out!