Move Sphinx plugins and format to Python package

[pao]

Right now, if packages want to use ReadTheDocs but want to share style with mainline Julia, it's a copy-and-paste job. I did this to get the julia domain for the StrPack.jl docs, but it would be better just to add a submodule dependency so we can track changes made to the upstream documentation format and keep the style in sync.

[ViralBShah]

I don't fully understand this one.

[pao]

By separating docs/{_themes,sphinx} from the main repository, packages can easily include them and create documentation that's visually unified with the main Julia documentation.

[ViralBShah]

That does sound like a good idea. I would suggest to just go for it.

[pao]

Someone would need to create a target repository in the JuliaLang account. I don't have the permission.

[ViralBShah]

I somehow missed this. Sorry about that. Should I create a JuliaDoc repository?

[ViralBShah]

Should this repository be a julia package itself? JuliaDoc.jl?

[pao]

That's an interesting thought--I'm not quite sure how that would work, though. I'll need to look into how to use external resources on RTFD.

[pao]

Right, so on further reflection, that doesn't make any sense--it contains Python code, not Julia code, and it's used by Sphinx, not the package. However, it would make sense to make it installable by pip. Then we tell RTFD to use a virtualenv, add the JuliaDoc Sphinx extension to requirements.txt, and drop that in the docs folder.

[pao]

In requirements.txt something like:

-e git+https://github.com/JuliaLang/JuliaDoc.git#egg=JuliaDoc

[ViralBShah]

Sorry - that is a bit cryptic for me. Where do I create requirements.txt?

[ViralBShah]

I created JuliaDoc, and you should have commit access.

[pao]

@ViralBShah thanks. The requirements.txt would be in each package's doc folder, along with config.py. I'll try to give this a whirl in the next couple of days.

[pao]

This was almost too easy: https://julia-docrepo.readthedocs.org/en/latest/ https://github.com/pao/julia/tree/doc-refactor

Before this can be pushed, the owner of our RTFD instance needs to go in and turn the "Use virtualenv" option on, and set doc/requirements.txt as the Requirements file. I checked that not having a requirements.txt won't break anything, but whoever makes the change should check to make sure.

[StefanKarpinski]

That would be me. @pao, if you give me your rtfd username, I can add you as an admin.

[StefanKarpinski]

Also, I made these changes. Might be easier if you're an admin though.

[pao]

Thanks, @StefanKarpinski; you'll be shocked to learn my RTFD username is "pao".

I'll push this through tomorrow, test on one of my packages, and fill out the JuliaDoc README. Will also port #2123 over to the new repository.

[pao]

Oh, and a post to -dev so packagers who are using Sphinx for docs know this is available.

[pao]

Just realized our translators will need to do the same thing. cc @wlbksy @lbenitesanchez @andrioni you will need to update your RTFD instances per #2379 to keep the Julia document style for the latest manual. Your 0.1 documentation, if applicable, will continue to work as before.

[pao]

Oops, @wlbksy, see ^ (mistyped your username)

[wlbksy]

received. would not find enough time until July. Thanks for noticing

[pao]

Between this and commits made to JuliaLang/JuliaDoc, this now supersedes #2123.

[pao]

For packages, looks like there's still a little work to do. Need to work out sidebar and proper hierarchy in topbar.

https://monadsjl.readthedocs.org/en/latest/ is my guinea pig.

[pao]

Ignore the build failure. Something went wrong in the tests on clang but this doesn't touch any Julia code. GCC went fine.

[pao]

Styles didn't quite come through right from #2123.

[pao]

Style differences were due to insecure content loading restrictions in Firefox Nightly. I have pushed to fix that, but that will still leave problems with MathJax-rendered content if we have any, due to readthedocs/readthedocs.org#283.

[pao]

Okay, I think I have this sorted out. There's still work to do to make this nice for packages, but this is serviceable and we can start working those issues on the JuliaDoc repo.

@StefanKarpinski @ViralBShah @nolta if someone else can give this a once-over and it looks good feel free to merge it.

[pao]

...no one likes reviewing doc stuff, apparently. I'll merge this secure in the knowledge we can back it out.

[quinnj]

I actually took a stab at implementing this documentation for the ODBC package and it was really easy!

https://odbcjl.readthedocs.org/en/latest/

Looking forward to getting this widespread.

[ViralBShah]

@pao Sorry for not chiming in earlier - busy preparing a talk for a few days. Merging this was the right thing.

[pao]

Great! I intend to get a post up soon, but thanks for taking the plunge, @karbarcca!

@ViralBShah, no problem, I know people are busy,

[ViralBShah]

BTW, make helpdb.jl barfs now on my mac, and I do not have pip. What do I do to get things working again in the new setup?

[pao]

Hmm. Unfortunately the Python packaging story is a messy business. Since we already require extra dependencies to build documentation, I'm inclined to just add pip (http:https://www.pip-installer.org/) to the list.

[ViralBShah]

Would it not work with easy_install?

[pao]

Apparently it can, including installing directly from git and --user, but I'd hate to use it if pip is available. Makefile magic is welcome.

[ViralBShah]

Mac has easy_install, but no pip. I guess this kind of thing would need to go into the Makefile. Have you announced this on the list and how people should use it and such? Perhaps the Example.jl package can be modified to use it.

[pao]

Haven't announced yet. Instructions are in the JuliaDoc README, and apparently they work if @karbarcca was able to get it going.

[quinnj]

I think the Juliadoc is pretty good, though honestly I just copied your
monad.jl doc folder and changed values, which ended up being really easy
for someone that knows almost nothing about how sphinx works. I still need
to track down a good formatting cheatsheet so a link would be helpful.
On Jun 4, 2013 12:25 AM, "pao" [email protected] wrote:

Haven't announced yet. Instructions are in the JuliaDoc README, and
apparently they work if @karbarcca https://github.com/karbarcca was
able to get it going.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2379#issuecomment-18889854
.

[JeffBezanson]

I'm trying to make html and I get:

Installing collected packages: JuliaDoc
  Running setup.py develop for JuliaDoc

    Creating /home/jeff/.local/lib/python2.7/site-packages/JuliaDoc.egg-link (link to .)
    JuliaDoc 0.0.0 is already the active version in easy-install.pth

    Installed /home/jeff/src/julia2/julia/doc/src/juliadoc
Successfully installed JuliaDoc
Cleaning up...
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.1.3

Exception occurred:
  File "/home/jeff/src/julia2/julia/doc/conf.py", line 15, in <module>
    import juliadoc
ImportError: No module named juliadoc
The full traceback has been saved in /tmp/sphinx-err-q0_u76.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http:https://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http:https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [html] Error 1

Help plz?

[pao]

That output doesn't include anything about module installation--do you have pip installed? If not, do you have easy_install?

I guess an alternative would be to pull it in as a submodule for the purposes of the main repository, and set PYTHONPATH in the Makefile. That would cover you if you don't have a functional Python packaging system installed.

[pao]

@JeffBezanson and @ViralBShah, give f1427a6 a try? Hopefully there is no problem which cannot be solved with submodules and doesn't create more problems.

[ViralBShah]

Thanks. So much easier to use now!

[scw]

I just tried building the docs on master, and hit the issue of getting RTD installed first. I fixed it by doing a pip install -r requirements.txt, but it'd be great if the change that @pao suggested could be merged so this wasn't necessary. Failing that, I can submit a patch to add the pip step to the README.me for the docs.

[pao]

The change I suggested is merged (f1427a6), but only covers the Julia-specific extensions to Sphinx. You still need Sphinx.

[scw]

I see, my mistake. I have Sphinx installed, but on OS X, this still left me with a failed import for sphinx_rtd_theme, when just following the instructions in doc/README.md.

[pao]

Ahh; I see that @nolta added that requirement recently with the new theme.