documentation-related suggestions, corrections, comments - evergreen

[mitzimorris]

Summary:

Note gaps in documentation here and/or suggestions for improvements

Description:

Perpetually open issue

Current Version:

[mitzimorris]

noted here: https://github.com/stan-dev/cmdstanpy/issues/173#issuecomment-597215511

I installed cmdstanpy on another windows 10 x64 machine. The only part where the instructions are unsatisfying (for a naive user like me) is Prerequisites \n CmdStanPy requires an installed C++ toolchain.

I figured the way to use the cmdstanpy.install_cxx_toolchain, but had to restart / set the path variable for the make file in order to get it running.

[mitzimorris]

comment from Ben Bales on CmdStanR - same goes for CmdStanPy

https://github.com/stan-dev/cmdstanr/issues/200#issuecomment-644159362

[tomwphillips]

I wasn't sure whether to create a new issue, so thought I'd post here. I would find it useful to be able to view the online documentation for the different versions of cmdstanpy. On a few occasions I've read the latest documentation online and found methods I would like to use, but then found that they're not in the latest pypi release.

Similarly, many other Python packages use GitHub releases to tag the commit corresponding to each version, which makes it easy to browse the code for a particular version, but that workflow isn't used here.

I have experience building CI/CD pipelines in Python projects at work (using CircleCI, but they're all quite similar), so I might be able to help out with some improvements if it's wanted. 🙂

[mitzimorris]

On a few occasions I've read the latest documentation online and found methods I would like to use, but then found that they're not in the latest pypi release.

not sure what you mean by latest documentation online? my understanding is that whenever a release is uploaded to pypi, that's what readthedocs is showing? is that not the case?

[mitzimorris]

Similarly, many other Python packages use GitHub releases to tag the commit corresponding to each version, which makes it easy to browse the code for a particular version,

https://github.com/stan-dev/cmdstanpy/issues/122 - just following the master / develop etc, so we can tag releases. going forward, will tag whenever a new version is uploaded to PyPi.

[tomwphillips]

On a few occasions I've read the latest documentation online and found methods I would like to use, but then found that they're not in the latest pypi release.

I can't for the life of me find the function I was looking at. Sorry, I should have provided more detail in the first place.

not sure what you mean by latest documentation online? my understanding is that whenever a release is uploaded to pypi, that's what readthedocs is showing? is that not the case?

Yes, readthedocs always shows the latest version on master. It would be useful to be able to read the documentation for the specific version I'm using.

[mitzimorris]

thanks alot for the link - I will get this working ASAP!

[mitzimorris]

expose helper functions API section of the docs

• set_cmdstan_path,
• cmdstan_path,
• set_make_env,
• install_cmdstan

[mitzimorris]

host CmdStanPy docs via GitHub as well as on readthedocs website -

• should this be just the Sphinx docs or something more comprehensive?
• how can we integrate this with Stan / CmdStan release process?

@serban-nicusor-toptal - need your help here.

also related - tried to address above comment:

Yes, readthedocs always shows the latest version on master. It would be useful to be able to read the documentation for the specific version I'm using.

cannot get the damn thing to get latest tagged version showing up. any thoughs?

[mitzimorris]

Document use of "--include_paths" as one of the stanc_options

[serban-nicusor-toptal]

Hey @mitzimorris We can have the docs be updated when we do a new release (tag) in ~~Jenkins~~ github. Let me how we should update the docs and if there are any other requirements. We already have the one in github automated afaik ( build-docs ) I'm a bit unsure about how to do the readthedocs one. I will look into the versioning for readthedocs see if I can figure it out!

[serban-nicusor-toptal]

Is it possible for you to give me access to the project dashboard in ReadTheDocs @mitzimorris ? ( My username is snick ) I think we need to either modify something in the dashboard or play around with the conf.py

Edit: We need to leverage the usage of stable but by default, it points to the latest release not individually to each.

[mitzimorris]

just gave you access to readthedocs - also tried changing setting to stable, but it doesn't seem to be picking up the version tag.

[mitzimorris]

@serban-nicusor-toptal - tagging you for above message

[serban-nicusor-toptal]

I've activated the v0.9.66 version here ( created a tag in github before ) and ran a build, after the build it shows up in the public list here. Let me know if it looks as it should. I'll implement this into Jenkins so we can use their api to activate a version and build it.

[mitzimorris]

@serban-nicusor-toptal - just a heads up - I'm going to move stuff around so that we'll also have docs via github pages - following instructions here: https://www.docslikecode.com/articles/github-pages-python-sphinx/

[mitzimorris]

docs are now available at: https://mc-stan.org/cmdstanpy/

~~what needs to be done for readthedocs.io config? I'm unclear on the following:~~

• ~~package is hosted on PyPi - PyPi links to docs on readthedocs.io~~
• ~~can readthedocs.io just serve the contents of the GitHub repo docs dir? where is it getting its config to build the docs from srcs using Sphinx?~~

updated readthedocs config: latest == develop, and path to conf.py is docsrc/conf.py

readthedocs can host multiple versions, whereas GitHub pages only serve the latest version. (Note: the stan-dev/docs repo is set up to get around this limitation via a bunch o' scripts). will update the README to make this more clear.

whenever we upload a new version to PyPi, we want a corresponding tagged version of the docs on readthedocs - do we need to do this ourselves via readthedocs admin?

I'm still unclear as to what the difference between "stable" and "latest" are and whether the default readthedocs page should be stable or latest. assuming that people are coming to this page from PyPi, it should be latest?

[serban-nicusor-toptal]

~~For readthedocs we can either have a trigger on cmdstanpy and when a new release(tag) is pushed we'll automatically use this job to activate and build that specific version on readthedocs or use the job by hand after a release.~~

From what I understood here is that we have selected develop for latest, which means latest will point to the newest code in develop ( head commit ) at any time. For stable, it will always point to the latest release (tag)

Edit: I went through their documentation and it looks like we don't need Jenkins at all here. They support webhook integration and automation rules. I've created a new rule that will activate and build any new tag created in github.

Edit 2: I have cleaned the test tags I did.

[mitzimorris]

From what I understood here is that we have selected develop for latest, which means latest will point to the newest code in develop ( head commit ) at any time. For stable, it will always point to the latest release (tag)

this makes sense - exactly what we need.

They support webhook integration and automation rules. I've created a new rule that will activate and build any new tag created in github.

excellent!

just created an issue w/r/t capturing this information - for now, put it into a wiki and hope that we can keep it up-to-date.

[mitzimorris]

I've created a new rule that will activate and build any new tag created in github.

nice!

one nagging readthedocs question: why doesn't stable show the tag? presumably, https://cmdstanpy.readthedocs.io/en/stable/ is 0.9.66 because it's linked to from PyPi - the previous version docset does show the tags: https://cmdstanpy.readthedocs.io/en/stable-0.9.65/

[serban-nicusor-toptal]

I would say that because stable always points to the latest release but showing it as stable, didn't find a way to override this. To make it look nicer we can disable stable and only have latest + releases (tags). What do you think? @mitzimorris

[mitzimorris]

disable stable and only have latest + releases (tags)

much better - completely explicit and removes question of what is meant by stable

[serban-nicusor-toptal]

I've changed default version here to latest and removed stable from the list. ( de-activated the version in versions list )

[mitzimorris]

great - this guy is asking the same question as I have - tldr: the answer seems to be "not possible" - https://github.com/readthedocs/readthedocs.org/issues/4529

When I locally build the documentation, I see the version number displayed in the top-left, under the project name, as expected.

But when I look at the read-the-docs documentation, this version number is replaced with "latest".

but enough about this - what we have is fine - many thanks @serban-nicusor-toptal !

[serban-nicusor-toptal]

Sadly I don't think we can change that, it's worth always keeping in mind that latest will point to the latest (head) commit in develop not to the latest release.

If latest is the trouble we can try the following:

1. We remove latest, and keep our naming convention only ( based on git tags ) without stable. In this way we can manually and through the api ( I think ) set the default version ( as in the above pic ). Ex: stable-0.9.65
2. We remove latest, put back stable which will always point to the stable version ( latest release/tag in github ) plus our naming convention. In this way we don't need to change default version as it would always point to stable version (the latest release).

What do you think @mitzimorris ?

Edit: We would still have the issue that stable will not show the exact version or commit, but at least we know it will be the latest stable release, makes more sense if you're not looking for development code/docs.

[mitzimorris]

if we can set the default version through the api, that would be nice, as readthedocs and github pages would match.

what would be ideal would be a release script for CmdStanPy that would, given a release tag:

• create an appropriately tagged branch
• update the file cmdstanpy/_version.py setting __version__ to the tag
• upload to PyPi
• update readthedocs default version
• generate html docs for develop branch to republish github pages

@serban-nicusor-toptal - how does this get set up? also, repo has file https://github.com/stan-dev/cmdstanpy/blob/develop/.gitlab-ci.yml. this file is a holdover from "pycmdstan", an earlier incarnation of this project. use this or delete?

[ahartikainen]

.gitlab-ci.yml can be deleted.

GH Actions can handle those requirements.

[mitzimorris]

just created issue #295 for release -

@ahartikainen and @serban-nicusor-toptal let me know what you need - I can send PyPi info

[mitzimorris]

https://github.com/stan-dev/cmdstanpy/issues/282

[mitzimorris]

#304