refactor doc into user-facing and dev-facing and by language about bridgestan

[WardBrian]

Can you clarify what parts of this you intend to appear on the rendered website at https://roualdes.github.io/bridgestan/ and what parts you want to live only on Github?

The website doc has all of its sources in python/docs since it uses sphinx, and splitting it across multiple folders will be quite messy.

If we wanted to, we could move the the python/docs folder to the top level docs/, but it would still be preferable if all the final docs intended to end up online were in the same folder

[bob-carpenter]

From @WardBrian on building the doc locally:

Building the docs locally requires installing (at minimum) sphinx, pydata-sphinx-theme, nbsphinx, and myst-parser. These are all available under those names from Pip.

At a maximum, if you want to also build the Julia and C++ doc, you need 'breathe' from pip, doxygen, and Julia 1.8 installed. These will be simply skipped if you don't have them.

Once you have the above installed, the build is done by running make html inside the python/docs/ folder. This will create a new sub-directory called python/docs/_build/html, with the files in there.

[bob-carpenter]

Can you clarify what parts of this you intend to appear on the rendered website at https://roualdes.github.io/bridgestan/ and what parts you want to live only on Github?

Sorry that wasn't clear. I'd be happiest if the .md files are just pointers to the rendered website.

we could move the the python/docs folder to the top level docs/, but it would still be preferable if all the final docs intended to end up online were in the same folder

I think it's worth moving them up to bridgestan/docs/ so they're easier for a developer to find. I couldn't find them until I just started looking through all the docs (I didn't even know what suffixes to search for, so I did it manually).

I'll revise the issue text to match what I say here.

[WardBrian]

I agree with the layout you now have in the top-level issue. Very clear, thanks!

How do you want to go about doing this? Is it easiest if I reorganize the docs folder (+ update our CI etc), leaving blank files to be filled in later (i.e., by you)?

[roualdes]

1. Under the bridgestan/docs, what is the difference between

   i. language-agnostic documentation and
   ii. docs/users/ for user-facing language-agnostic documentation?

2. Where are you thinking the subsection Tips from our README will go?

3. Last, some brainstorming. If, in the future, we expand on our suite of examples, will we accumulate code within each languages' subfolder and links in each languages' doc? I have in mind code examples beyond MCMC say Stein Variational Gradient Descent, other links to other projects using BridgeStan, or how to verify higher level AD with finite differences. Should we have an examples page that collects links to code and/or projects?

[WardBrian]

will we accumulate code within each languages' subfolder and links in each languages' doc?

I am happy to accumulate links in each languages' doc, code within each language's subfolder should stay pretty limited IMHO. For example, we actually got rid of MCMC.py in the Python folder, but I think it would be more than natural to link to @bob-carpenter's eventual library of samplers.

[bob-carpenter]

@roualdes:

1. I see doc as being for users, for devs, or for both. The stuff for both would go higher up. One of these may be the empty set. But right now, we have the .md files which are not language-specific and then things for each interface language.

2. Oops, forgot about the README.md. It does bring up the issue of platform-specific documentation.

   • I'm not sure why we're telling people that Windows needs forward slashes. Don't all of our makefiles use forward slashes?
   • the parameter size and ordering thing should go in language-agnostic user-facing doc as it cuts across languages; the former can just be a link to the Stan language reference section on transforms, as that gives the exact sizes. In any case, I don't think we want to start duplicating Stan language doc in this repo if we can avoid it---there's just no clear place to stop.
   • pre-reqs 1: I don't think we need to tell people they need an interface language; each language's doc can point to where to get that language if you think that's necessary
   • pre-reqs 2 & 3: everyone is going to need the C++ toolchain and CmdStan, so that's interface language agnostic
   • pre-reqs 4: ensuring tools are built and imported is also interface language-agnostic (though I don't see what brings in the latest Stan---I think it's missing a make stan-update command somewhere
   • acknowledgements: these are also language agnostic, but I think we can just drop them or at most mention them in dev-facing interface-agnostic doc

3. I don't think we should include code examples that use the interfaces in this repo; we can point to things like @roualdes library of Julia routines in the Julia-specific, user-facing doc

[bob-carpenter]

@WardBrian: If you could move things around, that'd be great. This'll probably also bring up some issues with my highly abstracted, idealized view of the world.

I can do it if you'd rather, but you're much faster and more accurate at this kind of thing than I am.

[WardBrian]

I'm not sure why we're telling people that Windows needs forward slashes. Don't all of our makefiles use forward slashes?

Windows natively uses backslashes, and these will work for things other than the CMDSTAN path (for example, you can do make .\path\to\model`)

pre-reqs 4: ensuring tools are built and imported is also interface language-agnostic (though I don't see what brings in the latest Stan---I think it's missing a make stan-update command somewhere

I don't think we want to recommend people use make stan-update. For example, if you did this right now, bridgestan would break due to the JSON dependency move. We should keep people on the released versions, which don't need any extra steps (the tarball already has the submodules)

@bob-carpenter see #44 for moving things around in a basic way. I didn't move around the contents of the docs, I figured that is more editorial and can be done as the new pages get written, it just moves it to the top-level folders and fixes the CI, etc.

[roualdes]

Thought of one more related question this weekend. We currently have a Compatibility subsection of our README, listing some OS cross compiler versions for which we've tested BridgeStan. Should we continue to list these in our doc, just update our test matrix to include the newer version of GCC for which we just had an issue reported, neither, or both?

[WardBrian]

Compatibility subsection of our README, listing some OS cross compiler versions

Good point! I believe list is primarily based off the versions we were all personally using before we had any CI. Our CI tests the following:

Ubuntu 20.04, GCC 9.4.0
MacOS 11.7, Clang 13.0.0
Windows Server 2022 (Windows 10 based), Msys GCC 5.3.0¹.

I have also personally updated to Ubuntu 22.04/GCC 11.2.0 since that bug report came in last week, and I've tested it on Windows 11 as well.

I think it is worth noting the versions we test on in the installation instructions, but saying if you have a version which doesn't work you should let us know. The exception to this is probably anything on Windows besides gcc would be a miracle in my opinion.

Footnotes

1. I'm only 80% sure of this, I believe it is using RTools40 but there are multiple GCCs available in the Github runner) ↩

[WardBrian]

How do we feel about this issue given the current state of the doc and the changes to the installation in #51?

[bob-carpenter]

We should sit down and figure out a doc plan for the whole repo after CmdStan is removed and everything's updated.

I still like the idea of factoring docs into user-facing and dev-facing by language, but I'm open to alternative suggestions that don't turn user-facing installs into a logic puzzle.

[WardBrian]

CmdStan dependency is gone, so we can now take the time to review the current state of the docs and decide on any changes we want to make.

My 2 cents is that that a user/developer breakdown here is probably even fuzzier than in other projects, and I think our doc will always presume a bit more technical know-how than something like CmdStanR's, due to the nature of the project.

To me there are really 3 things to document:

1. How to install the pre-requisites, download, and use Bridgestan (in a way that is generic over language used). A Getting Started Guide, essentially. We have the start of one now.
2. How to install and use a specific language binding. I think the existing docs are contain most of what is needed here, but perhaps it needs to be reorganized. A more fleshed out example in each language's section of the docs would also be nice.
3. How the internals of bridgestan are organized and work (this is mostly language independent but can link to the specific FFI docs for each interface).

I'm not sure what dev facing doc is required besides 3. If you understand the core FFI ideas, each of the languages' interfaces is a standard package for that language. I suppose you could break 3 into a truly language-agnostic page and then 3 truly language-specific pages, but I think there would be a lot of repetition and cross linking required to make that as useful as a single document which covers it all

[bob-carpenter]

I mostly agree with @WardBrian here.

I would restrict (1) to just pre-requisites and a high-level overview of functionality. The how to install and use BridgeStan in an interface seems like it's going to need to be done on a language-by-language basis and thus belongs in (2).

For (3), we also need to list things that need to be installed beyond the user-facing apps (like test frameworks). That can probably just be a list of which packages need to be installed for devs. I don't actually see that we'll need to do a lot of ongoing development for this interface that we can't just do ourselves.

Then after 1.0, we can think about moving it over to stan-dev. I was mainly concerned about not getting a giant group involved in the design and initial coding. Now that it's complete, I'd be happy to move it over.

[roualdes]

Both of you make good points: simplify (1), move language specific install to (2), and add a dev dependencies to (3).

I'd like to see interface installation instructions closer to language interface instructions than we currently have in our docs. In my mind, this is in line with the points you all are making.

[bob-carpenter]

I agree that the install instructions and API docs should go together for each interface. Those are the two of the pieces of what I meant by user-facing doc. The third useful piece would be a hello world/getting started doc like we have for our other interfaces.