Makefile for building Sphinx documentation on Windows

[debjan]

Hi,

I "ported" basic IPython Sphinx documentation Makefile to Windows so that make <target> also works on Windows.
I tested all switches successfully, then additionally produced PDF output of current stable 0.13 release, through MiKTeX: http://goo.gl/XRasR

make.cmd:

@ECHO OFF
REM ~ Windows command line make file for Sphinx documentation

SETLOCAL

SET SPHINXOPTS=
SET SPHINXBUILD=sphinx-build
SET PAPER=
SET SRCDIR=source

IF "%PAPER%" == "" SET PAPER=a4
SET ALLSPHINXOPTS=-d build\doctrees -D latex_paper_size=%PAPER% %SPHINXOPTS% %SRCDIR%

FOR %%X IN (%SPHINXBUILD%.exe) DO SET P=%%~$PATH:X

FOR %%L IN (html pickle htmlhelp latex changes linkcheck) DO (
    IF "%1" == "%%L" (
        IF "%P%" == "" (
            ECHO.
            ECHO Error: Sphinx is not available. Please make sure it is correctly installed.
            GOTO END
        )
        MD build\doctrees 2>NUL
        MD build\%1 || GOTO DIR_EXIST
        %SPHINXBUILD% -b %1 %ALLSPHINXOPTS% build\%1
        IF NOT ERRORLEVEL 0 GOTO ERROR
        ECHO.
        ECHO Build finished. Results are in build\%1.
        IF "%1" == "pickle" (
            ECHO Now you can process the pickle files or run
            ECHO    sphinx-web build\pickle to start the sphinx-web server.
        )
        IF "%1" == "htmlhelp" (
            ECHO Now you can run HTML Help Workshop with the
            ECHO    .hhp project file in build/htmlhelp.
        )
        IF "%1" == "linkcheck" (
            ECHO Look for any errors in the above output
            ECHO    or in build\linkcheck\output.txt.
        )
        GOTO END
    )
)

IF "%1" == "clean" (
    RD /s /q build dist %SRCDIR%\api\generated 2>NUL
    IF ERRORLEVEL 0 ECHO Build environment cleaned!
    GOTO END
)

ECHO.
ECHO Please use "make [target]" where [target] is one of:
ECHO.
ECHO    html      to make standalone HTML files
ECHO    pickle    to make pickle files (usable by e.g. sphinx-web)
ECHO    htmlhelp  to make HTML files and a HTML help project
ECHO    latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
ECHO    changes   to make an overview over all changed/added/deprecated items
ECHO    linkcheck to check all external links for integrity
GOTO END

:DIR_EXIST
ECHO.
ECHO Info: Run "make clean" to clean build environment

:ERROR
ECHO.
ECHO Error: Build process failed!

:END
ENDLOCAL

Cheers

[fperez]

This looks good, could you please submit it as a pull request so that our Windows devs can test it directly? That way the code can be reviewed giving you specific feedback and it will be merged (if accepted) with credit directly to you from the commit records. Thanks!

[debjan]

Hi,
I tried to do that, but it turned out as a bad idea :(

I don't know this git system and now I can't say it's too friendly to new users. After reading the docs and dense terminology I made a fork of IPython, than cloned whole repository locally and linked to "upstream" repo. Now I copied this tiny and not-at-all-important batch script in IPython's docs folder. I did commit and push.

It turned out, I had to make new branch in my fork and commit there instead. OK, google to revert possibly my mistake. Found some clue and did it. Made new branch and redid commit. Going to pull request I see 3 commits, while I expected just last one.

Sorry if I made you additional trouble.
Please forget this stupid script

Cheers

[Carreau]

I don't know this git system and now I can't say it's too friendly to new users. After reading the docs and dense terminology I made a fork of IPython, than cloned whole repository locally and linked to "upstream" repo. Now I copied this tiny and not-at-all-important batch script in IPython's docs folder. I did commit and push.

Looking at your history, it seems like you make everything right

It turned out, I had to make new branch in my fork and commit there instead. OK, google to revert possibly my mistake. Found some clue and did it. Made new branch and redid commit. Going to pull request I see 3 commits, while I expected just last one.

That might have been a github issue that sometime need a few hours when you force push to fix things.

Sorry if I made you additional trouble.

There is no trouble, we re really happy when people propose patches, and most of the time we tend to guide them to learn how to do thing even if it takes more time than doing it ourselves. So if you want to try again, please do so, and don't hesitate to ask for advice.

You can have a look at github for windows if you dislike the comandline , github also just released try github in your browser.

Please forget this stupid script

There no stupid script, and we are really low on people using IPython on windows. so any fixes are welcome.
So if you just don't want / don't have time to learn how to do things, just say so and someone else will make a PR.

[fperez]

Reopening because I still think it's a worthwhile contribution. Indeed @debjan, we can try to help you out if you are having difficulties, and if nothing else one of us can make the PR.

If you are very new to git and github, you might want to try the new github tutorial which seems quite nicely done. There are also some nice intro videos on the git site you may find useful.

[fperez]

ps - I'm sure that investing a little bit of time familiarizing yourself with the git/github workflow now will pay tremendous dividends for you in the long run, by increasing your ability to participate in open source project development (whether with ipython or in other projects).

[debjan]

Thanks for your kind support and I'm glad I didn't messed things around here :)

I don't have problem with general prompt, to me DOS and BASH commands are intuitive, but not git command names and workflow just now.
Working remotely adds a bit unsettling feeling too, and I accept that learning git basics through example in reality is worth the effort.

I went to easy route, by just reforking IPython repo and making correct steps, learned from past mistake.
Here is my hopefully valid request: #2104

Cheers guys

[fperez]

On Thu, Jul 5, 2012 at 3:16 PM, debjan
reply@reply.github.com
wrote:

Thanks for your kind support and I'm glad I didn't messed things around here :)

Great, glad to see you persevered. I'm sure you'll find in the long
run it pays off.

Forgive us if it takes us a few days to review your PR, we're all
super busy and several core devs are on vacation, so it may take us a
bit of time. But don't worry, we'll get to it.

Regards,

f

[minrk]

closed by #2104