Custom build params

[Swader]

Suggest adding possibility of providing custom build params and flags.

Related to #1554, more specifically this build error.

Due to alternative conf files in locale subfolders, the build fails, looking for stuff in the folders where the conf.py was found.

Locally, I successfully build with:

    sphinx-build -b html -d _build/doctrees -D language='xx' -c locale/xx/ . _build/html/xx/

where xx is the locale I'm building for. I would like the ability to provide these arguments to RTD's builder as well, so that I may replicate my local build process exactly.

Or is there another way to accomplish this?

[ericholscher]

The Language setting on the project will pass the proper language code to
Sphinx.

On Wed, Aug 19, 2015 at 6:07 AM, Bruno Škvorc notifications@github.com
wrote:

Suggest adding possibility of providing custom build params and flags.

Related to #1554 #1554,
more specifically this build error
https://readthedocs.org/builds/rtdsphinx-php/3255152/.

Due to alternative conf files in locale subfolders, the build fails,
looking for stuff in the folders where the conf.py was found.

Locally, I successfully build with:

sphinx-build -b html -d _build/doctrees -D language='xx' -c locale/xx/ . _build/html/xx/

where xx is the locale I'm building for. I would like the ability to
provide these arguments to RTD's builder as well, so that I may replicate
my local build process exactly.

Or is there another way to accomplish this?

—
Reply to this email directly or view it on GitHub
#1573.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[Swader]

Yes, but unless the build process runs from the root folder and targets the locale/xx folder for the extended conf file, it won't work (see build error) because it's looking for sources in the folder where I told RTD the conf file was under Advanced Settings. If there were a way to have it run the builder from / but look for the config file in locale/xx, that would solve things. It would be easier if Sphinx supported a source folder argument, but from what I can tell so far, that isn't so.

[ericholscher]

Why don't you just have one config file that has the locale dir set to
locale, and then let us or the user configure the language at build time?

On Wed, Aug 19, 2015 at 9:19 AM, Bruno Škvorc notifications@github.com
wrote:

Yes, but unless the build process runs from the root folder and targets
the locale/xx folder for the extended conf file, it won't work (see build
error) because it's looking for sources in the folder where I told RTD the
conf file was under Advanced Settings. If there were a way to have it run
the builder from / but look for the config file in locale/xx, that would
solve things. It would be easier if Sphinx supported a source folder
argument, but from what I can tell so far, that isn't so.

—
Reply to this email directly or view it on GitHub
#1573 (comment)
.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[Swader]

Well... now I feel stupid. Thanks, never thought of that.

I've now successfully built both on RTD, but redirecting to the Croatian version from the English one does not work: http://rtdsphinx-php.readthedocs.org/en/latest/

I have set the Croatian version (rtdsphinx-php-hr) as the translation of the main one, but when I click on "hr" to switch the language, the browser is redirected to a hr subset of the main project (rtdsphinx-php) rather than rtdsphinx-php-hr.

[ericholscher]

the /hr/ work and be an alias for that project. I looked into it, and the
syncing code is triggered on project save -- but not on the addition of the
translation. I went ahead and saved your project, and it should be working
now -- We should be firing that syncing task on translation save though,
too.

On Wed, Aug 19, 2015 at 9:53 AM, Bruno Škvorc notifications@github.com
wrote:

Well... now I feel stupid. Thanks, never thought of that.

I've now successfully built both on RTD, but redirecting to the Croatian
version from the English one does not work:
http://rtdsphinx-php.readthedocs.org/en/latest/

I have set the Croatian version (rtdsphinx-php-hr
http://rtdsphinx-php-hr.readthedocs.org/hr/latest/) as the translation
of the main one, but when I click on "hr" to switch the language, the
browser is redirected to a hr subset of the main project (rtdsphinx-php)
rather than rtdsphinx-php-hr.

—
Reply to this email directly or view it on GitHub
#1573 (comment)
.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[ericholscher]

The idea is that you can define "translations" and they will live at the
/langcode/ on the parent project, so that it provides a nice UX/UI.

On Wed, Aug 19, 2015 at 10:17 AM, Eric Holscher eric@ericholscher.com
wrote:

the /hr/ work and be an alias for that project. I looked into it, and the
syncing code is triggered on project save -- but not on the addition of the
translation. I went ahead and saved your project, and it should be working
now -- We should be firing that syncing task on translation save though,
too.

On Wed, Aug 19, 2015 at 9:53 AM, Bruno Škvorc notifications@github.com
wrote:

Well... now I feel stupid. Thanks, never thought of that.

I've now successfully built both on RTD, but redirecting to the Croatian
version from the English one does not work:
http://rtdsphinx-php.readthedocs.org/en/latest/

I have set the Croatian version (rtdsphinx-php-hr
http://rtdsphinx-php-hr.readthedocs.org/hr/latest/) as the translation
of the main one, but when I click on "hr" to switch the language, the
browser is redirected to a hr subset of the main project (rtdsphinx-php)
rather than rtdsphinx-php-hr.

—
Reply to this email directly or view it on GitHub
#1573 (comment)
.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[ericholscher]

In the future we hope not to require multiple RTD Projects to provide
translations, and to be able to support it on one main Project -- which is
what this approximates, but is definitely not the best possible solution.

On Wed, Aug 19, 2015 at 10:18 AM, Eric Holscher eric@ericholscher.com
wrote:

The idea is that you can define "translations" and they will live at the
/langcode/ on the parent project, so that it provides a nice UX/UI.

On Wed, Aug 19, 2015 at 10:17 AM, Eric Holscher eric@ericholscher.com
wrote:

the /hr/ work and be an alias for that project. I looked into it, and the
syncing code is triggered on project save -- but not on the addition of the
translation. I went ahead and saved your project, and it should be working
now -- We should be firing that syncing task on translation save though,
too.

On Wed, Aug 19, 2015 at 9:53 AM, Bruno Škvorc notifications@github.com
wrote:

Well... now I feel stupid. Thanks, never thought of that.

I've now successfully built both on RTD, but redirecting to the Croatian
version from the English one does not work:
http://rtdsphinx-php.readthedocs.org/en/latest/

I have set the Croatian version (rtdsphinx-php-hr
http://rtdsphinx-php-hr.readthedocs.org/hr/latest/) as the
translation of the main one, but when I click on "hr" to switch the
language, the browser is redirected to a hr subset of the main project
(rtdsphinx-php) rather than rtdsphinx-php-hr.

—
Reply to this email directly or view it on GitHub
#1573 (comment)
.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[Swader]

This is fantastic, thank you! Full post on SitePoint coming soon, with caveats, tips and tricks so others don't trip up like I did here. Thanks again!

[ericholscher]

Thanks again for the awesome stuff you're writing up as well. I think it
will help a lot -- I think that our work with
https://github.com/rtfd/sphinx-autoapi might be useful for the PHP
community soon also. We are working to integrate third party autodoc tools
into Sphinx in a nice way, which I think will be quite powerful. If there
is a preferred PHP doc API doc tool that generates JSON or some other
parsable format, we should be able to integrate it pretty easily, for a
full featured prose & api doc solution that allows references back and
forth.

On Wed, Aug 19, 2015 at 10:24 AM, Bruno Škvorc notifications@github.com
wrote:

Closed #1573 #1573.

—
Reply to this email directly or view it on GitHub
#1573 (comment).

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[Swader]

That's really interesting.
I had begun work on a tool that turns PHP source code into PHP domain friendly format via Sage, but the entire foray into Sphinx and RTD was actually so that I could write proper API + prose docs (a combination), something no other system offers out of the box and Sphinx comes closest to. But with autoapi, that might be handled, if configured properly. Will definitely keep an eye on it.

[ericholscher]

Yea, that's exactly what autoapi is doing -- but it will be fully supported
on RTD when we're done. What tool were you using to pull out the PHP source
docs?

On Wed, Aug 19, 2015 at 10:53 AM, Bruno Škvorc notifications@github.com
wrote:

That's really interesting.
I had begun work on a tool that turns PHP source code into PHP domain
friendly http://pythonhosted.org/sphinxcontrib-phpdomain/ format via
Sage https://github.com/dotink/sage/, but the entire foray into Sphinx
and RTD was actually so that I could write proper API + prose docs (a
combination), something no other system offers out of the box and Sphinx
comes closest to. But with autoapi, that might be handled, if configured
properly. Will definitely keep an eye on it.

—
Reply to this email directly or view it on GitHub
#1573 (comment)
.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[Swader]

I played around with Apigen's internals, PhpDocumentor's token parsers and Sage, but didn't get a very smooth workflow out of any of them so far (only been toying with this over the past few days).