Add smv_prebuild_command config option

[samtygier-stfc]

Can be used to run a command in the checked out director before building
with sphinx.

[samtygier-stfc]

I made this before spotting #46 . For me it is a better solution to make this config option than a command line argument.

[dgarcia360]

Related issue #45

This solution would work for my use case as well instead of #46. A nice improvement for the future could be supporting multiple commands separated by commas.

[samtygier-stfc]

Separating with ; or && should already work as the command is called with shell=True.

[fritz-hh]

This is exactly what I was looking for in my issue #68.
@Holzhaus: It would be great to have this merged in sphinx-multiversion! Do you think that would fit in?

[temporaer]

it'd be nice to add some environment variables for the prebuild command, particularly the sphinx output path. This way, version-specific artifacts can be generated. For example, I'm zipping some example files and would like to put them in the _static folder so the docs can have a link to download them.

[samuel-emrys]

Looks like I raised issue #71 prematurely - it looks like this will resolve what I'm after.

@samtygier-stfc this is failing the CI build for relatively trivial linting reasons - are you able to run flake8 and black over these files and push the changes to fix the CI issues?

@Holzhaus is there anything else preventing this from getting merged in?

[samuel-emrys]

Actually, while I'm thinking about it - would it be worth adding post build functionality too? I'm thinking that for build targets like pdf, there's an additional step after running sphinx-build where the generate .tex files need to be compiled using latex.

[samtygier-stfc]

I've updated the branch, fixing the flake8 errors and adding a smv_postbuild_command.

[fritz-hh]

Thanks a lot for the implementation of the smv_prebuild_command option. It helped me a lot!
It would be great to see it integrated in master

[milvert]

@Holzhaus When is planned to be merged to master?

[Cedric-Magnan]

This PR is truly useful.

Until it is merged into a new release, if that can be useful to any of you, I have deployed the modified package on PyPI in order to be able to use the modifications in other projects that may want to use this unavailable feature :
https://pypi.org/project/sphinx-multiversion-pre-post-build/

I can see that I am not the only one who had this idea :
https://pypi.org/project/sphinx-multiversion-scylla/

@Holzhaus, this is definitely a temporary solution for me, so don't hesitate to tell me if you want this PyPI package deleted.

[samuel-emrys]

This PR is truly useful.

Until it is merged into a new release, if that can be useful to any of you, I have deployed the modified package on PyPI in order to be able to use the modifications in other projects that may want to use this unavailable feature :
https://pypi.org/project/sphinx-multiversion-pre-post-build/

I can see that I am not the only one who had this idea :
https://pypi.org/project/sphinx-multiversion-scylla/

@Holzhaus, this is definitely a temporary solution for me, so don't hesitate to tell me if you want this PyPI package deleted.

For awareness, you can install this using pip without having to deploy to pypi: https://pip.pypa.io/en/stable/cli/pip_install/#vcs-support

To install from the authors branch:

pip install git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command

[oesteban]

Although I agree this could be useful, the example of apidoc is a bad one - current master of sphinx-multiversion will successfully run apidoc automatically if the sphinxcontrib-apidoc package is correctly set up (checked myself).

It won't run autodoc correctly (#69), though, but I would say that is a combined effect of how sphinx imports modules (and how Python keeps them cached for the whole execution while sphinx does not importlib.reload them). I guess that discussion should be had with the linked issue.

EDIT: fix link to the correct issue.

[samuel-emrys]

One use case that I have for this is integrating doxygen and breathe into the build process for documenting C++ projects. I was hopeful that this would solve this for me, but alas it does not.

The issue is that breathe does not export the xml database that doxygen spits out, and relies on the doxygen xml output directly. This is fine for the build stage, but the doxygen build directories obviously don't get exported to the version outputdir and gets nuked along with the rest of the tmp directory, and so they're inaccessible when actually rendering the documentation. This would be resolved if i could specify the names of directories to export to the version outputdir

I realise that this is a very specific use case, so to generalise it a bit perhaps there's utility in also being able to specify a directory/pattern of directories to export after running the prebuild/postbuild command?

my proposal is to add the following command options:

smv_prebuild_export_pattern
smv_prebuild_export_destination
smv_postbuild_export_pattern
smv_postbuild_export_destination

[Genfood]

Why is this PR still open? Is some help needed that it gets merged? Please let me know, I really like it to be part of Sphinx Multiversion.

[samtygier-stfc]

I can rebase if that is useful. My project has stop using this in favour of the versioning in pydata-sphinx-theme https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html . This works better for us, as it saves the problem of building old docs in a current environment.

[Genfood]

I can rebase if that is useful.

I guess it would be pretty useful, because we would like to build automatically api docs from our code.

My project has stop using this in favour of the versioning in pydata-sphinx-theme https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html . This works better for us, as it saves the problem of building old docs in a current environment.

Does this also work with apidocs?