[RFC] Migrated to Sphinx

[dantleech]

This PR migrates the tutorial to sphinx and adds a theme.

http://phpcr.readthedocs.org/en/latest/

[wjzijderveld]

Probably change this README?
I'd leave a notice you based it on the doctrine theme.

[dantleech]

Actually this theme is now a default theme (pyramid) but I forgot to delete this README :)

[dantleech]

OK. I have split the tutorial into chapters.

Open for comments but no proof reading just yet :P

http://phpcr.readthedocs.org/en/latest/

[wouterj]

About the API link thing. That's done by the sensio.sphinx.phpcode extension provided by fabpot/sphinx-php. It allows you to configure a url, but if doesn't allow you to change the format. To make it work with the format used by http://phpcr.github.io/doc/html/ , you need to tweak the replace arguments to use a dot instead of a slash:

def php_namespace_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    text = utils.unescape(text)
    env = inliner.document.settings.env
    base_url = env.app.config.api_url
    has_explicit_title, title, namespace = split_explicit_title(text)

    try:
        full_url = base_url % namespace.replace('\\', '.') + '.html'
    except (TypeError, ValueError):
        env.warn(env.docname, 'unable to expand %s api_url with base '
                 'URL %r, please make sure the base contains \'%%s\' '
                 'exactly once' % (typ, base_url))
        full_url = base_url + utils.escape(full_class)
    if not has_explicit_title:
        name = namespace.lstrip('\\')
        ns = name.rfind('\\')
        if ns != -1:
            name = name[ns+1:]
        title = name
    list = [nodes.reference(title, title, internal=False, refuri=full_url, reftitle=namespace)]
    pnode = nodes.literal('', '', *list)
    return [pnode], []

def php_class_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    text = utils.unescape(text)
    env = inliner.document.settings.env
    base_url = env.app.config.api_url
    has_explicit_title, title, full_class = split_explicit_title(text)

    if len(re.findall(r'[^\\]\\[^\\]', rawtext)) > 0:
        env.warn(env.docname, 'backslash not escaped in %s' % rawtext, lineno)

    try:
        full_url = base_url % full_class.replace('\\', '.') + '.html'
    except (TypeError, ValueError):
        env.warn(env.docname, 'unable to expand %s api_url with base '
                 'URL %r, please make sure the base contains \'%%s\' '
                 'exactly once' % (typ, base_url))
        full_url = base_url + utils.escape(full_class)
    if not has_explicit_title:
        class_name = full_class.lstrip('\\')
        ns = class_name.rfind('\\')
        if ns != -1:
            class_name = class_name[ns+1:]
        title = class_name
    list = [nodes.reference(title, title, internal=False, refuri=full_url, reftitle=full_class)]
    pnode = nodes.literal('', '', *list)
    return [pnode], []

def php_method_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    text = utils.unescape(text)
    env = inliner.document.settings.env
    base_url = env.app.config.api_url
    has_explicit_title, title, class_and_method = split_explicit_title(text)

    ns = class_and_method.rfind('::')
    full_class = class_and_method[:ns]
    method = class_and_method[ns+2:]

    if len(re.findall(r'[^\\]\\[^\\]', rawtext)) > 0:
        env.warn(env.docname, 'backslash not escaped in %s' % rawtext, lineno)

    try:
        full_url = base_url % full_class.replace('\\', '.') + '.html' + '#method_' + method
    except (TypeError, ValueError):
        env.warn(env.docname, 'unable to expand %s api_url with base '
                 'URL %r, please make sure the base contains \'%%s\' '
                 'exactly once' % (typ, base_url))
        full_url = base_url + utils.escape(full_class)
    if not has_explicit_title:
        title = method + '()'
    list = [nodes.reference(title, title, internal=False, refuri=full_url, reftitle=full_class + '::' + method + '()')]
    pnode = nodes.literal('', '', *list)
    return [pnode], []

def setup(app):
    app.add_config_value('api_url', {}, 'env')
    app.add_role('namespace', php_namespace_role)
    app.add_role('class', php_class_role)
    app.add_role('method', php_method_role)

And then configure http://phpcr.github.io/doc/html/files/phpcr.src. as the api_url in conf.py

[xabbuh]

I think it shouldn't be a problem to make the format configurable.

[wouterj]

No, but I don't have enough Python knowledge. You can just follow the steps done with api_url and use that for the format.

[xabbuh]

Shouldn't be that hard. If you need it I can create a pull request making it configurable.

[dantleech]

Regarding the API links .. its a bit of a non-issue currently as we hardly reference any classes by their names currently.

I have done a quick proof-reading of the reformatted documentation and made some fixes.

Shall we merge this and link to readthedocs from the website?

[dbu]

this should be 2.1

[dbu]

+1 for this, i like it.

can you please also update the README to link to phpcr.github.io and the new readthedocs page?
lets fix the version thing and the README, then merge and do further improvements on the live thing.

[dantleech]

Updated, merging ..

[xabbuh]

Just FYI, the URL pattern is now configurable in the Sphinx extension (if you ever have the need to use it).