I'm happily using a remote theme (like the excellent Just the docs) for my public github pages (like here).
It is as simple as adding remote_theme: pmarsceill/just-the-docs to the _config.yml file.
Now I wanted to use this for a GitHub Enterprise (GHE) instance. I only got an unspecified error "Github page generation failed". I tried 3 options:
Just have the entry remote_theme: pmarsceill/just-the-docs
added the host remote_theme: 'https://github.com/pmarsceill/just-the-docs'
Cloned the repository to GHE: remote_theme: myuser/just-the-docs
None of that worked.
What do I miss?
Related
I'm trying to clone the repo https://github.com/TowerofHanoi/towerofhanoi.github.io on my GitHub, based on the website https://toh.necst.it and publish it on a new GitHub pages instance. I'm doing this to check that a new article is well formatted for publication.
I'm having trouble generating the website on GitHub pages, the site is somehow bad: https://mencucci.github.io/towerofhanoi.github.io/ (my repo: https://github.com/Mencucci/towerofhanoi.github.io).
Locally on my Ubuntu machine, I can get the site to render properly with the following commands:
bundle init
bundle add jekyll
rm -rf \_site && bundle exec jekyll serve --verbose
I couldn't get the remote to build properly.
I tried:
adding a valid theme (no changes)
using a custom build action (no changes)
I noticed a difference in the logs: local, and github. The local log references the /_layout directory, but the remote one does not. Maybe it doesn't "see" the theme?
Thank you for your time
Figured it out, my main issue was that I was running the site using the default url, which hosts the site at <username>.github.io/<repo_name>. Some hard coded elements assumed that the site be hosted at domain root instead. I solved my issue by using a custom domain, which mapped the to the base domain (empty path).
I have a basic ReadTheDocs repository. As per the advice of the build page, I sought to use a .readthedocs.yml to configure it:
Configure your documentation builds! Adding a .readthedocs.yml file to your project is the recommended way to configure your documentation builds. You can declare dependencies, set up submodules, and many other great features.
I added a basic .readthedocs.yml:
version: 2
sphinx:
builder: dirhtml
fail_on_warning: true
and got a build failure:
Problem in your project's configuration. Invalid "sphinx.builder": .readthedocs.yml: Your project is configured as "Sphinx Html" in your admin dashboard, but your "sphinx.builder" key does not match.
This was surprising as it seemed contrary to the guidance in the admin dashboard at https://readthedocs.org/dashboard/PROJECTNAME/advanced/ which led me to assume that I could set whatever I liked in the admin dashboard, but it would be overridden by my .readthedocs.yml (which is the behaviour I expected and wanted):
These settings can be configured using a configuration file. That's the recommended way to set up your project. Settings in the configuration file override the settings listed here.
I updated the setting in the admin dashboard to match the .readthedocs.yml and then got a build error:
Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/PROJECT_NAME/checkouts/latest/source/contents.rst not found
which looks like https://github.com/readthedocs/readthedocs.org/issues/2569 (RTD not finding Sphinx configuration) - but it's not clear why that's happening because prior to adding .readthedocs.yml, the project built just fine.
I'm struggling to model what's actually going on here:
The config file isn't acting as an "overlay" / "override" onto the web settings - as per the first error, some forms of disagreement are a build failure
It's almost like if the config file exists, the web config is ignored - this would explain the contents.rst issue arising, but this isn't consistent with the first error
Adding a python.install entry to .readthedocs.yml eventually got the site building, but it's still not clear to me if I'm generally doing the right thing, and/or how successful future config changes will be.
The reason you're getting the error is that the sphinx version you're using locally doesn't match with the version readthedocs is using at the time you initiated the build process.
See here: You can use a requirements.txt file to use the same version of sphinx you use locally. I had the same issue. I've solved it by simply adding my version Sphinx==3.1.2
Also, I added a .readthedocs.yml file in my project directory where docs/ resides, pointing to where the conf.py because
I was using an extension sphinxcontrib.napoleon which readthedocs build process fails to recognize.
Wanted readthedocsbuild process to use a specific version on Sphinx.
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 1
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml
# Optionally build your docs in additional formats such as PDF
formats:
- pdf
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: docs/requirements.txt
a
and added all the dependencies needed to generate the documentation in docs/requirement.txt
Babel==2.8.0
imagesize==1.2.0
readme-renderer==26.0
Sphinx==3.1.2
sphinx-argparse==0.2.5
sphinx-rtd-theme==0.5.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-images==0.9.2
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-napoleon==0.7
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4
GitLab doesn't render HTML for me, but just display the source code:
Background: I used sphinx to generate the HTML and tried to show the doc at GitLab.
I looked at other projects' repositories, such as pandas, sphinx. They only have .rts files in the repository, and not HTML files. I guess they generate HTML for their websites but don't upload to Git.
I don't have a website and want to show doc at GitLab. Is there a way to do that? Or do I have to generate other formats (other than HTML, e.g. PDF) instead?
First of all, Git and products like GitLab and GitHub are different things. Git doesn't ever render anything; it's a version control system. It doesn't have a web interface.
Secondly, GitLab's core product isn't supposed to render anything. It's not a web host, it's a tool for hosting, sharing, and managing Git repositories. However you might want to try GitLab Pages:
GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab.
You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations. You can also attribute any license to your content.
Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate).
GitLab Pages will publish content from the public/ directory of your repository, so you should move your files there. You will also need a .gitlab-ci.yml file in the root of your repository containing something like
image: alpine:latest
pages:
stage: deploy
script:
- echo 'Nothing to do...'
artifacts:
paths:
- public
only:
- master
(taken from the sample repository). Add that file, then commit and push. After deployment is complete, your site should be available at https://youruser.gitlab.io/yourproject.
Note that GitHub has a similar product (that works differently).
Finally,
I looked at other projects' repositories, such as pandas, sphinx. They only have .rts files in the repository, and not HTML files. I guess they generate HTML for their websites but don't upload to Git.
it's very likely that the reStructured Text files are the only source that exists, and that HTML is generated from them automatically. Sphinx this format by default. If you're interested in working from another format like Markdown or reStructured Text you may want to explore GitLab Pages' support for static site generators.
There is a super easy solution I found on this post:
Before:
https://gitlab.com/[user]/[repository]/raw/[branch]/[filename.ext]
After:
Development (throttled)
https://gl.githack.com/[user]/[repository]/raw/[branch]/[filename.ext]
Production (CDN)
https://glcdn.githack.com/[user]/[repository]/raw/[branch]/[filename.ext]
Another solution:
At the root of your repo, add a file called .gitlab-ci.yml containing the following lines:
pages:
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
Your file should then be available at
https://your-username.gitlab.io/project-name/filename.html
See this post for details: Gitlab: host and render HTML files
I've created a new jekyll project precisely following the simple command sequence at https://jekyllrb.com/. However it seems like the server is not looking for the right main.css:
GET http://example.com/css/main.css 404 (Not Found)
This error in the browser console seems to imply an irrelevant domain for a local project, so I wonder whether those instructions just mentioned are not what one should do for bootstrapping and running/testing a jekyll project on your local server. In that case, what is the right procedure for working locally? and is there an automated command for setting a different host name for deploying to a real server?
I am using a fresh install of jekyll 3.2.1.
Thanks!
Dirty temporary patch (because of this issue).
In _config.yml, set url: http://matanster.github.io/bloglike or wathever is your production url.
Create a config_dev.yml and add url: http://127.0.0.1
Locally, you can serve with :
bundle exec jekyll serve --config _config.yml,_config_dev.yml
I built a site using a php openshift project and accessing the root directory via http works fine. However, all the root directories give me a 404 not found, like this one: http://test.toppagedesign.com/sites/
I checked with ssh, and /app-root/repo/sites and app-deployments/current/repo/sites/ both exist.
EDIT
Added a directory called php and now I have 503 errors for everything...
EDIT 2
I deleted the php directory, now the 503 errors are gone. However, I do still get 404 errors for the subdirectory.
Here is my directory tree: http://pastebin.com/hzPCsCua
And I do use git to deploy my project.
php is one of the alternate document roots that you can use, please see the March Release blog post here about this (https://www.openshift.com/blogs/openshift-online-march-2014-release-blog)
As for the sub-directories not working, can you ssh into your server and use the "tree" command to post the directory/file structure of your project? Also are you using Git to deploy your project or editing files directly on the server?
You need to have an index.php or index.html file in any directory that you want to work like app-domain.rhcloud.com/sites , if you just have sub-directories, how would it know what to show? Also, indexing (showing a folders contents) is not enabled for security reasons, and I believe there is no way to enable it.
This sounds like it could be a problem with how you are serving your static content.
I recently created a new sample app for OpenShift that includes:
a basic static folder
an .htaccess file (for serving assets in production)
support for using php's local server to handle the static content (in your dev environments)
Composer and Silex - a great starting point for most new PHP apps
You can serve the project locally if you have PHP-5.4 (or better), available in your dev environment:
php -S localhost:8080 -t static app.php
For a more advanced project that is built on the same foundation, take a look at this PHP+MongoDB mapping example. I wrote up a blog post with some notes on my process for composing that app as well.
Hope these examples help!