clarify runtime expectations

[gojomo]

trafficstars

Motivated by discussion thread: https://groups.google.com/g/gensim/c/ZnuJkxWT6ps/m/x5pXQgU8AAAJ

Related: it seems there's an exact duplicate of this file in project-path /gensim/docs/src/**auto_examples**/tutorials. I think that (& sibling plain .py files there) are just automatic copies of these canonical versions, so I haven't applied the change there. (And perhaps, even though we want to commit the other sphinx-build outputs there, we don't want the duplicate .py sources there?)

[piskvorky]

Thanks! I'm also not sure what the "canonical" vs generated paths are, or Sphinx *.py duplication, deferring to @mpenkov .

[mpenkov]

Code under auto_examples is essentially a copy. We do keep it under version control (reasons below), but you shouldn't have to change it manually yourself. Instead, rebuild the gallery, and Sphinx will update those files for you. You can then add them to the PR.

The reason why we keep these duplicate files under version control is to keep Sphinx happy. If those files are missing, then Sphinx will attempt to rebuild the gallery from the source files, by running each of them individually. This takes time (hours). We want to avoid that, because we want our documentation to build relatively quickly from a fresh clone of the repo.

[mpenkov]

@gojomo @piskvorky Our CI now shows you what needs to be done:

The gallery cache appears stale.

Rebuild the documentation using the following commands from the gensim root subdirectory:

    pip install -e .[docs]
    make -C docs/src html

and then run `git add docs/src/auto_examples` to update the cache.

Stale files: ['docs/src/auto_examples/tutorials/run_doc2vec_lee.py']

This has been around for a while, but other linting issues with the PR were masking it.