Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added Installation guide for Gitlab Pages #597

Merged
merged 7 commits into from
Jan 9, 2022
Merged

Added Installation guide for Gitlab Pages #597

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6ce3763
added again
kolibril13 Sep 11, 2021
f7a1a40
Update doc/usage.ipynb
kolibril13 Sep 11, 2021
103ec44
Update doc/usage.ipynb
kolibril13 Sep 11, 2021
6da300d
Apply suggestions from code review
kolibril13 Oct 1, 2021
4ca5c5f
Update doc/usage.ipynb
kolibril13 Oct 1, 2021
ab729b6
Update doc/usage.ipynb
kolibril13 Oct 1, 2021
7ab3c69
made improvements
kolibril13 Oct 31, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 34 additions & 2 deletions doc/usage.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -695,6 +695,38 @@
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Automatic Creation of HTML and PDF output on GitLab Pages\n",
"\n",
"When using GitLab pages, you can use nbsphinx by adding the file `.gitlab-ci.yml` to your repo and copy the following code into this file:\n",
kolibril13 marked this conversation as resolved.
Show resolved Hide resolved
mgeier marked this conversation as resolved.
Show resolved Hide resolved
"```\n",
"image: python\n",
"\n",
"before_script:\n",
" - apt-get update -y\n",
mgeier marked this conversation as resolved.
Show resolved Hide resolved
" - apt-get install -y pandoc\n",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I normally like to add the --no-install-recommends, which might speed up the installation.

I've also just added this to nbsphinx's own CI: #598.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good!
But when the new nbspinx version will have it on default, will " - apt-get install -y pandoc\n", be needed at all?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand. It will still need pandoc (at least until #36 is done).

"\n",
"\n",
"pages:\n",
" stage: deploy\n",
" script:\n",
" - pip install numpy ipykernel\n",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about recommending the usage of a doc/requirements.txt instead?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer it like this, then it is ready for copy+paste

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, fair enough.

" - pip install sphinx nbsphinx\n",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sphinx is a dependency of nbsphinx, so it's not strictly necessary.

But if you prefer to mention it, that's fine.

" - mkdir -p doc; cd doc\n",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is that supposed to mean?

Is there no doc directory yet?
Where is the source directory?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I saw this somewhere on the internet and as it was working, I just applied it without spending much thought on it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I don't understand how this can work.

According to the sphinx-build call below, your source files are in doc/source but why are you creating the doc directory? It should exist already?

" - sphinx-build -b html source ../public/\n",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this will create a ../public/.doctrees directory which is not supposed to be published.

I think it would be good to use the -d to put the doctrees somewhere else.

Or are hidden directories ignored by Gitlab Pages anyway?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, this is only copy-pasted form some internet forums, I don't know about the details

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's fine, but do you know if the .doctree directory is served by Gitlab pages?
Do you have an example project where I can have a look?

" - echo 'Done'\n",
kolibril13 marked this conversation as resolved.
Show resolved Hide resolved
" artifacts:\n",
" paths:\n",
" - public\n",
" only:\n",
" - master\n",
"```"
]
},
{
"cell_type": "code",
"execution_count": null,
"outputs": [],
kolibril13 marked this conversation as resolved.
Show resolved Hide resolved
"source": [
"## HTML Themes\n",
"\n",
Expand Down Expand Up @@ -836,7 +868,7 @@
"\n",
"If you know of another Sphinx theme that should be included here, please open an [issue on Github](https://github.com/spatialaudio/nbsphinx/issues).\n",
"An overview of many more themes can be found at https://sphinx-themes.org/."
]
],
kolibril13 marked this conversation as resolved.
Show resolved Hide resolved
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -895,4 +927,4 @@
},
"nbformat": 4,
"nbformat_minor": 4
}
}
kolibril13 marked this conversation as resolved.
Show resolved Hide resolved