HPCE/gitea-pages
HPCE/gitea-pages
0
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Activity

added more detail about the pdf generation process and also updated the pdfs

Browse Source
This commit is contained in:
Tom Johnson 2017-12-28 21:14:39 -08:00
parent 4b4666e9e1
commit 744754a9c9
8 changed files with 9335 additions and 9555 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
_data/sidebars/mydoc_sidebar.yml
View File

@ -220,10 +220,6 @@ entries:
url: /mydoc_push_build_to_server.html
output: web, pdf
- title: Getting around the password prompts in SCP
url: /mydoc_no_password_prompts_scp.html
output: web, pdf
- title: Publishing on Github Pages
url: /mydoc_publishing_github_pages.html
output: web, pdf

2
index.md
View File

@ -7,6 +7,8 @@ permalink: index.html
summary: These brief instructions will help you get started quickly with the theme. The other topics in this help provide additional information and detail about working with other aspects of this theme and Jekyll.
---
{% include note.html content="If you'd like to keep up on best practices for documentation, see my <a alt='technical writing blog' href='http://idratherbewriting.com'>technical writing blog: I'd Rather Be Writing</a>." %}
## Build the Theme
Follow these instructions to build the theme.

55
pages/mydoc/mydoc_generating_pdfs.md
View File

@ -11,13 +11,9 @@ folder: mydoc
## PDF overview
This process for creating a PDF relies on Prince XML to transform the HTML content into PDF. Prince costs about $500 per license. That might seem like a lot, but if you're creating a PDF, you're probably working for a company that sells a product, so you likely have access to some resources.
This process for creating a PDF relies on Prince XML to transform the HTML content into PDF. Prince costs about $500 per license. That might seem like a lot, but if you're creating a PDF, you're probably working for a company that sells a product, so you likely have access to some resources. There's also a free license that prints a small "P" watermark on your title page, so if you're fine with that, great.
The basic approach is to generate a list of all pages that need to be added to the PDF, and then add leverage Prince to package them up into a PDF.
It may seem like the setup is somewhat cumbersome, but it doesn't take long. Once you set it up, building a pdf is just a matter of running a couple of commands.
Also, creating a PDF this way gives you a lot more control and customization capabilities than with other methods for creating PDFs. If you know CSS, you can entirely customize the output.
The basic approach is to generate a list of all web pages that need to be added to the PDF, and then add leverage Prince to package them up into a PDF. Once you set it up, building a pdf is just a matter of running a couple of commands. Also, creating a PDF this way gives you a lot more control and customization capabilities than with other methods for creating PDFs. If you know CSS, you can entirely customize the output.
## Demo
@ -25,6 +21,49 @@ You can see an example of the finished product here:
<a target="\_blank" class="noCrossRef" href="{{ "pdf/mydoc.pdf"}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
To generate the PDF, browse to the theme's directory in your terminal and run this script:
```bash
. pdf-mydoc.sh
```
This builds a PDF for the documentation in the theme. Look in the **pdf** folder for the output, and see the "last generated date" to confirm that you generated the PDF.
To build a PDF for the other sample projects, run these commands:
```bash
. pdf-product1.sh
```
or
```bash
. pdf-product2.sh
```
You can see the details of the script in these files in the theme's root directory. For example, open pdf-mydoc.sh. It contains the following:
```bash
# Note that .sh scripts work only on Mac. If you're on Windows, install Git Bash and use that as your client.
echo 'Kill all Jekyll instances'
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
clear
echo "Building PDF-friendly HTML site for Mydoc ...";
bundle exec jekyll serve --detach --config _config.yml,pdfconfigs/config_mydoc_pdf.yml;
echo "done";
echo "Building the PDF ...";
prince --javascript --input-list=_site/pdfconfigs/prince-list.txt -o pdf/mydoc.pdf;
echo "Done. Look in the pdf directory to see if it printed successfully."
```
After stopping all Jekyll instances, we build Jekyll using a special configuration file that specifies a unique stylesheet. The build contains a file (prince-list.txt) that contains a list of all pages to be included in the PDF. We feed this list into a Prince command to build the PDF.
The following sections explain more about the setup.
## 1. Set up Prince
Download and install [Prince](http://www.princexml.com/doc/installing/).
@ -66,6 +105,8 @@ Also note that there's a `output: pdf` property in case you want to make some of
In the configuration file, customize the values for the `print_title` and `print_subtitle` that you want. These will appear on the title page of the PDF.
We will access this configure file in the PDF generation script.
## 3. Make sure your sidebar data file has titlepage.html and tocpage.html entries
There are two template pages in the root directory that are critical to the PDF:
@ -292,7 +333,7 @@ Because the theme uses JavaScript in the CSS, you have to add the `--javascript`
## 5. Customize and run the PDF script
Duplicate the pdf-mydocf.sh file in the root directory and customize it for your specific configuration files.
Duplicate the pdf-mydoc.sh file in the root directory and customize it for your specific configuration files.
```
echo 'Killing all Jekyll instances'

17
pages/mydoc/mydoc_icons.md
View File

@ -12,6 +12,23 @@ folder: mydoc
## Font icon options
The theme has two font icon sets integrated: Font Awesome and Glyphicons Halflings. The latter is part of Bootstrap, while the former is independent. Font icons allow you to insert icons drawn as vectors from a CDN (so you don't have any local images on your own site).
## External icons
When you link to an external site, like [Jekyll](http://jekyllrb.com), an icon appears after the link. If you want to remove this icon, comment out this style in css/customstyles.css.
```css
/* this part adds an icon after external links, using FontAwesome*/
a[href^="http://"]:after, a[href^="https://"]:after {
content: "\f08e";
font-family: FontAwesome;
font-weight: normal;
font-style: normal;
display: inline-block;
text-decoration: none;
padding-left: 3px;
}
```
## See Font Awesome icons available
Go to the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/) to see the available icons.

132
pages/mydoc/mydoc_no_password_prompts_scp.md
View File

@ -1,132 +0,0 @@
---
title: Getting around the password prompts in SCP
sidebar: mydoc_sidebar
tags: [publishing, troubleshooting]
permalink: mydoc_no_password_prompts_scp.html
summary: "You can publish your docs via SSH through a Terminal window or more likely, via a shell script that you simply execute as part of the publishing process. However, you will be prompted for your password with each file transfer unless you configure passwordless SSH. The basic process for setting up password less SSH is to create a key on your own machine that you also transfer to the remote machine. When you use the SCP command, the remote machine checks that you have the authorized key and allows access without a password prompt."
folder: mydoc
---
## Get rid of password prompts
To remove the password prompts when connecting to servers via SSH:
1. On your local machine, go to your .ssh directory:
```
cd ~/.ssh
```
Note that any directory that starts with a dot, like .ssh, is hidden. You can view hidden folders by enabling them on your Mac. See [this help topic](http://ianlunn.co.uk/articles/quickly-showhide-hidden-files-mac-os-x-mavericks/). Additionally, when you look at the files in a directory, use ls -a instead of just ls to view the hidden files.
If you don't have an .ssh directory, create one with `mkdir .ssh`.
2. Create a new key inside your .ssh directory:
```
ssh-keygen -t rsa
```
3. Press **Enter**. When prompted about "Enter file in which to save the key ...", press ```Enter``` again.
This will create a file called id_rsa.pub (the key) and id_rsa (your identification) in this .ssh folder.
When prompted for a passphrase for the key, just leave it empty and press **Enter** twice. You should see something like this:
```
tjohnson-mbpr13:.ssh tjohnson$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/yourname/.ssh/id_rsa.
Your public key has been saved in /Users/yourname/.ssh/id_rsa.pub.
The key fingerprint is:
9a:8f:b5:495:39:78:t5:dc:19:d6:29:66:02:e8:02:a0 yourname@yourname-mbpr99.local
```
The key's randomart image is:
```
+--[ RSA 2048]----+
|. |
|+ |
|E |
|o. . |
|.. = o S |
|.&^ + 7i = o |
| = B . |
| o O + |
| *.o |
+-----------------+
```
As you can see, RSA draws a picture for you. Take a screenshot of the picture, print it out, and put it up on your fridge.
4. Open up another terminal window (in iTerm, open another tab), and SSH in to your remote server:
```
ssh <your_username>@remoteserver.com
```
5. Change `<your_username>` to your actual username, such as tjohnson.
When you connect, you'll be prompted for your password.
When you connect, by default you are routed to the personal folder on the directory. For example, `/home/remoteserver/<your_username>`. To see this directory, type `pwd` (or `dir` on Windows).
6. Create a new directory called .ssh on remoteserver.com server inside the `/home/remoteserver/<your_username>` directory.
```
mkdir -p .ssh
```
You can ensure that it's there with this command:
```
ls -a
```
Without the -a, the hidden directory won't be shown.
7. Open another Terminal window and browse to /Users/<your_username>/.ssh on your local machine.
```
cd ~/.ssh
```
8. Copy the id_rsa.pub from the /.ssh directory on your local machine to the /home/remoteserver/<your_username>/.ssh directory on the remoteserver server:
```
scp id_rsa.pub <your-username>@yourserver.com:/home/remoteserver/<your-username>/.ssh
```
9. Switch back into your terminal window that is connected to remoteserver.com, change directory to the .ssh directory, and rename the file from id_rsa.pub to `authorized_keys` (without any file extension):
```
mv id_rsa.pub authorized_keys
```
10. Change the file permissions to 700:
```
chmod 700 authorized_keys
```
Now you should be able to SSH onto remoteserver without any password prompts.
11. Open another terminal (which is not already SSH'd into remoteserver.com) and try the following:
```
ssh <your_username>@remoteserver.com
```
If successful, you shouldn't be prompted for a password.
Now that you can connect without password prompts, you can use the scp scripts to transfer files to the server without password prompts. For example:
```
scp -r ../doc_outputs/mydoc/writers <your-username>@remoteserver:/var/www/html/
```
{% include links.html %}

2
pdf-mydoc.sh
View File

@ -1,6 +1,6 @@
# Note that .sh scripts work only on Mac. If you're on Windows, install Git Bash and use that as your client.
echo 'Killing all Jekyll instances'
echo 'Kill all Jekyll instances'
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
clear

18678
pdf/mydoc.pdf
View File

File diff suppressed because it is too large Load Diff

BIN
pdf/product1.pdf
View File

Binary file not shown.