Move src->master and master->docs

[isuruf]

cc @HaoZeke

[HaoZeke]

Ah sorry I missed this! So as per the GH org rules, only master is built by default, a docs subfolder can be built on any branch, but I'm not sure that would be a good idea because:

• I can't think of a good reason to keep track of the generated documentation files in version control on the same branch as the source

A minor practical issue is an org admin needs to set the subfolder serve up. Will bring this up. Note that this is only if we are to continue to use GH-Pages, which is also a bit up in the air right now since Travis has started enforcing restrictions on FOSS projects and Symengine is looking for a different CI.

[isuruf]

I meant the branches. src branch should be renamed to master and master branch to docs

[isuruf]

Symengine is looking for a different CI.

I don't where you got this from, but it's news to me.

[HaoZeke]

I meant the branches. src branch should be renamed to master and master branch to docs

Yup, I understood that. It would appear that Github now allows arbitrary branches to serve as sources. Will have the rename done on Thursday then (the admin needs to choose the source branch).

I don't where you got this from, but it's news to me.

Personal correspondence. For context see:

• What Travis CI has mentioned w.r.t. billing
• Their line on forcing people off travis.org

[isuruf]

cc @certik, @asmeurer

Can we please make decisions in the public?

[isuruf]

Why does travis-ci matter where we host the webpages? We can use another CI if travis-ci stops working for us

[HaoZeke]

Yup, it actually does not. I was thinking that if we transition to a CI like Netlify (for the docs, not the tests) then it makes no sense to host the generated files in the repo on any branch (and therefore not use GH Pages at all). They claim benefits over GH-Pages in terms of latency, post-processing, etc. etc. (promotional yet possibly relevant context)

Of course as long as we are using gh-pages the CI is irrelevant.

Also it was not a decision at all, so much as an offhand discussion (about the CI)...

[asmeurer]

I would suggest doing like https://github.com/sympy/sympy.github.com. We have "sources" and "gh-pages". I would recommend not having "master" because it confuses people (people will assume they should commit to "master"). gh-pages is clear that it's the built docs. The sources branch can be named anything. You can make the default branch anything and you can also make the gh-pages branch anything.

@isuruf I think you have to make the branch name changes whatever is decided, since you have the access to the settings for this repo.

[isuruf]

Sounds good to me. @HaoZeke, let me know if you are fine with that and I'll do the change

[HaoZeke]

Hi @isuruf, sure anytime would be good!

[isuruf]

Also, master is being pushed by the CI in https://github.com/symengine/symengine where the doxygen docs are built. I don't understand why we need a separate repo https://github.com/symengine/api-docs

[HaoZeke]

It was split to avoid going over the Travis job minutes cap. The docs need around 7-8 minutes to build at the moment, which is for just the C++ API.

Also because the plan is to have all the APIs built simultaneously, so not just the C++ doxygen, but also the Python binding API docs will be harvested. The current structure allows for this, by keeping the main symengine repo along with the bindings as submodules.

[isuruf]

Why should the APIs be built in a separate repo? Each individual repo should have CI to test that docs are properly made and they can push the built docs. Each repo knows how to build their own docs. It doesn't make sense to centralize them. Also, how are the docs going to get updated? The current way it is set up, when there's a push to master in the repo, the docs get built. If we have a separate repo called api-docs, how is that going to get updated?

[HaoZeke]

The point of centralizing them is so we can query them jointly with intersphinx in the tutorials. Each repo can trigger a build of the docs, I'm looking into the deploy keys needed for that. For that matter, other than the C++ doxygen build, there aren't any docs being built at all right now.

[isuruf]

The point of centralizing them is so we can query them jointly with intersphinx in the tutorials.

There's intersphinx_mapping property that is useful for referencing other projects. See https://github.com/inducer/sumpy/blob/8e4a826ce11631e92514a8cd7f17ab02848dad6e/doc/conf.py#L311-L322 for an example

[HaoZeke]

Yup, but they require sphinx docs. Apart from the python and c++ bindings that is a bit of a chore to accomplish in each repo. I was planning on using doxyrest for generating ReST documentation for the rest. Now doxyrest has quite a few dependencies, so it makes little sense to me, to add a build pipeline and dependencies in each repo of the project. Also, it would be (from a user point of view) perhaps less accessible to have:

juliabindings.symengine.com pybindings.symengine.com etc..

Instead of a single api.symengine.com which could then benefit from having a good TOC structure.

[isuruf]

I was planning on using doxyrest for generating ReST documentation for the rest.

R has its own documentation which is what is used in symengine.R. Julia has its own documentation tools too. (I might have a branch somewhere with initial support)

Also, it would be (from a user point of view) perhaps less accessible to have:

They could be api.symengine.com/julia, api.symengine.com/python, etc.

[HaoZeke]

I feel like we should circle back to this when I have a concrete example. A different issue would be good, since the rename is complete (thanks), I'll close this.

However, the issue is still that R native documentation, and other language specific API docs cannot be used for intersphinx mappings.