Hi,
I would like to ask if there is a step-by-step guide how to deploy Sphinx docs on github repository?
I was shown this before how to do it, but I do not remember each step.
I can build documentation locally using “invoke docs” that creates a “dist” folder with html files:
In github → settings I set up the docs folder:
In my old repo, I see that I created a separate branch “gh-pages”. But I do not recall what are the next steps. I created this new branch like this in git bash:
git switch --orphan gh-pages
git commit --allow-empty -m "Initial commit on orphan branch"
git push -u origin gh-pages
How can I create docs and push it to github?
Because I can only invoke docs on main branch not gh-pages .
hi,
building locally is just for testing.
there is no need to push the locally built docs to the remote repo.
if you created your repo from the cookiecutter template, the workflows for building and deploying the docs should already be in place.
in the settings of the repo, under pages, just select the root of the gh-pages branch to serve the docs from.
let me know if that doesn’t work…
Hi,
I set the branch to gh-pages, but deployment failed:
Yes I created package using cookiecutter and documented every step, since I am good in making simple things complicated:
Do I need to create any additional files in gh-pages branch? Or does it has smth to do with these urls in config file?
the ROOT of the gh-pages branch, not the DOCS folder…
I also tried that, the deployment is not failed but the url is 404 not found, even after waiting for quite some time.
your docs workflow fails so that would not be so surprising.
Thank you for pointing this error out, I did not know I could check it here.
Could you please help me to find out what is causing this error?
Any reason why the path returns NoneType not a string filepath?
Because locally I can build the package “pip install -e .”, I can also “invoke docs”.
The error message says that eigen directory is not a string. But this line was a default from the original package.
The error message :
File "<string>", line 1, in <module>
File "/home/runner/work/compas_wood/compas_wood/setup.py", line 61, in <module>
get_eigen_include(),
File "/home/runner/work/compas_wood/compas_wood/setup.py", check_suite_focus=true#step:3:133) return os.path.join(conda_prefix, 'include', 'eigen3')
File "/usr/lib/python3.8/posixpath.py", line 76, in join
a = os.fspath(a)
check_suite_focus=true#step:3:136) TypeError: expected str, bytes or os.PathLike object, not NoneType
Dear @tomvanmele
The problem is that this line returns None in the setup.py file when hosted on github:
conda_prefix = os.getenv('CONDA_PREFIX')
Why os.getenv could return none? Is it somehow related that this package is not pushed to conda-forge? Any ideas why this directory is not found? Why this package needs to be built on github, while only documentation is needed to be built?
the docs.yml workflow is not properly configured for a C++ based package. have a look at compas_cgal/docs.yml at main · compas-dev/compas_cgal · GitHub and adapt yours accordingly…
@brgcode thanks, trying this the whole day…
docs.yml is complaining about sphinx:
Does it have anything to do regarding these two warning appearing locally?
@tomvanmele documentation is built when sphinx is downgraded to 2.4 in requirements-dev.txt
It at least builds but looks in a wrong format.
Any ideas what happened with the template appearance?
Or which file is responsible for that?
compas_wood - compas_wood (ibois-epfl.github.io)
This is locally invoked:
set the theme to 0.15.8 in requirements-dev.txt
sphinx_compas_theme >=0.15.8
and add this to conf.py
html_static_path = sphinx_compas_theme.get_html_static_path()
@brgcode The result is the same.
if sphinx is set to >=3.4 there is the same error
if sphinx is set to ==2.4 builds, but bad formatting of website as before.
I set sphinx_compas_theme >=0.15.8
I added html_static_path = sphinx_compas_theme.get_html_static_path()
as far as i can tell, your docs a building correctly.
however, they seem to be pointing to a broken dev folder instead of to latest.
please try removing the dev folder from the gh-pages branch and change index.html to
<meta http-equiv="refresh" content="0; url=/compas_wood/latest/">
1 Like
Nice. Thank you very much. Works perfectly.
My last point from the multiple questions I had, is Conda.
Do you have any references how to push the package to conda-forge?
I never done this before and have no knowledge about conda-forge process.
Shall I open a new question in the compas forum regarding this?
the process of submitting a package at conda-forge is controlled by the admins of conda-forge. you have to follow the steps described in their guidelines
https://conda-forge.org/docs/maintainer/adding_pkgs.html
as usual, compas_cgal is a good reference for writing the required recipe. the feedstock of compas_cgal can be found here GitHub - brgcode/compas_cgal-feedstock: A conda-smithy repository for compas_cgal.
a feedstock is created automatically once your PR at conda-forge is approved and merged…
Thank you I will try to read the references you mentioned.
And concerning the files in the compas_cgal package.
Could you tell me what file where specifically added to push to conda-forge?
Are these two files are the only ones?
Thank you for all your help and patience. I really enjoy compas framework and debugging c++ code through compas_view2 is somewhat easier and more straight forward than what I was used to, knowing that building and display time is relatively short.
2 Likes
