PDF with all pages + Reader-friendly mcdocs (hosted on github).

[shafr]

This commit adds:

• PDF with all pages that is available in Github actions Generate PDF book (mdpdf) job. It is re-generated with current date every time push / pull is made. See example in my repo
• Friendly Reader. Only problem - that if pages order is changed or new pages are added - you need to manually update mkdocs.yml index. Check site here..

After you would merge - please go to Settings -> Pages and choose gh-pages branch (which is generated by mkdocs).
You'll get a github-hosted reader-friendly pages.

[oprypin]

that if pages order is changed or new pages are added - you need to manually update mkdocs.yml index

Why didn't you follow my advice to use a plugin for that?
mkdocs/mkdocs#2561 (comment)
I can help if you ran into some issue.
Anyway, I wrote out the solution here https://github.com/shafr/CEH-in-bullet-points/pull/1, hope you can use it.
If you merge it into your master, it will also appear in this pull request.

[shafr]

Hello @oprypin, I didn't want to bother you with extra issues.
I think my main concern was that for some reason sidebar index & pagination was not respecting index provided by .md file.

I wanted to be least intrusive to the existing files, so I took README.md and just extracted chapters into separate file index.md & then ran script:

sed -i -re "s;[0-9]+\.;\*;g" index.md

[shafr]

Also for some reason your code does not work:

(CEH-in-bullet-points) ➜  CEH-in-bullet-points git:(plug) ✗ mkdocs serve -v
INFO     -  Building documentation...
DEBUG    -  Loading configuration file: /code/github_help/CEH/CEH-in-bullet-points/mkdocs.yml
DEBUG    -  Loaded theme configuration for 'material' from '/code/github_help/CEH/CEH-in-bullet-points/lib/python3.8/site-packages/material/mkdocs_theme.yml': {'language': 'en', 'direction': None, 'features': [], 'palette': {'primary': None, 'accent':
            None}, 'font': {'text': 'Roboto', 'code': 'Roboto Mono'}, 'icon': None, 'favicon': 'assets/images/favicon.png', 'include_search_page': False, 'search_index_only': True, 'static_templates': ['404.html']}
DEBUG    -  Config value: 'config_file_path' = '/code/github_help/CEH/CEH-in-bullet-points/mkdocs.yml'
DEBUG    -  Config value: 'site_name' = 'CEH-IN-BULLET-POINTS'
DEBUG    -  Config value: 'nav' = None
DEBUG    -  Config value: 'pages' = None
DEBUG    -  Config value: 'site_url' = ''
DEBUG    -  Config value: 'site_description' = None
DEBUG    -  Config value: 'site_author' = None
DEBUG    -  Config value: 'theme' = Theme(name='material', dirs=['/code/github_help/CEH/CEH-in-bullet-points/lib/python3.8/site-packages/material', '/code/github_help/CEH/CEH-in-bullet-points/lib/python3.8/site-packages/mkdocs/templates'],
            static_templates=['sitemap.xml', '404.html'], locale=Locale(language='en', territory=''), language='en', direction=None, features=[], palette={'primary': None, 'accent': None}, font={'text': 'Roboto', 'code': 'Roboto Mono'}, icon=None,
            favicon='assets/images/favicon.png', include_search_page=False, search_index_only=True)
DEBUG    -  Config value: 'docs_dir' = '/code/github_help/CEH/CEH-in-bullet-points/chapters'
DEBUG    -  Config value: 'site_dir' = '/tmp/mkdocs_nzxnpn44'
DEBUG    -  Config value: 'copyright' = None
DEBUG    -  Config value: 'google_analytics' = None
DEBUG    -  Config value: 'dev_addr' = Address(host='127.0.0.1', port=8000)
DEBUG    -  Config value: 'use_directory_urls' = True
DEBUG    -  Config value: 'repo_url' = ''
DEBUG    -  Config value: 'repo_name' = ''
DEBUG    -  Config value: 'edit_uri' = ''
DEBUG    -  Config value: 'extra_css' = []
DEBUG    -  Config value: 'extra_javascript' = []
DEBUG    -  Config value: 'extra_templates' = []
DEBUG    -  Config value: 'markdown_extensions' = ['toc', 'tables', 'fenced_code']
DEBUG    -  Config value: 'mdx_configs' = {}
DEBUG    -  Config value: 'strict' = False
DEBUG    -  Config value: 'remote_branch' = 'gh-pages'
DEBUG    -  Config value: 'remote_name' = 'origin'
DEBUG    -  Config value: 'extra' = {}
DEBUG    -  Config value: 'plugins' = PluginCollection([('gen-files', <mkdocs_gen_files.plugin.GenFilesPlugin object at 0x7f576d5f7a90>), ('literate-nav', <mkdocs_literate_nav.plugin.LiterateNavPlugin object at 0x7f576d613e80>)])
INFO     -  Cleaning site directory
[Errno 2] No such file or directory: '/code/github_help/CEH/CEH-in-bullet-points/gen_index.py'

I've done installation of

pip install mkdocs-material mkdocs-literate-nav mkdocs-gen-files

[shafr]

Also I'm using venv:

(CEH-in-bullet-points) ➜  CEH-in-bullet-points git:(plug) ✗ python --version
Python 3.8.10

(CEH-in-bullet-points) ➜  CEH-in-bullet-points git:(plug) ✗ pip list
Package                    Version
-------------------------- -------
click                      8.0.1  
ghp-import                 2.0.1  
importlib-metadata         4.8.1  
Jinja2                     3.0.1  
Markdown                   3.3.4  
MarkupSafe                 2.0.1  
mergedeep                  1.3.4  
mkdocs                     1.2.2  
mkdocs-gen-files           0.3.3  
mkdocs-literate-nav        0.4.0  
mkdocs-material            7.2.6  
mkdocs-material-extensions 1.0.3  
packaging                  21.0   
pip                        20.0.2 
pkg-resources              0.0.0  
Pygments                   2.10.0 
pymdown-extensions         8.2    
pyparsing                  2.4.7  
python-dateutil            2.8.2  
PyYAML                     5.4.1  
pyyaml-env-tag             0.1    
setuptools                 44.0.0 
six                        1.16.0 
watchdog                   2.1.5  
zipp                       3.5.0 

[oprypin]

Also for some reason your code does not work:

@shafr Agh sorry, I forgot to include that actual file ☹️ - now it's there

[undergroundwires]

Hi @shafr , this is awesome. I'm sorry for responding too late. I had other priorities and did not have time to put love i needed to here. I'd like to merge it and even highlight you as contributor, but there has been some force-pushes and the history looks wrong now. I try to resolve the conflicts but I don't have access to your branch

Could you please on your branch:

git fetch origin master
git rebase origin/master

And then it will guide you. As long as you run git add to necessary files and continue with git rebase --continue it should resolve all conflicts. I could resolve it this way, but I cannot update the PR.

This is the best and biggest contribution so far and looks very clean, but to have proper review we need to solve these conflicts, thank you again and happy new year.

[shafr]

I've done manual merge - everything should be in sync with master (maybe job workflows/quality-checks.yml was renamed that is not taken into account)

[shafr]

@undergroundwires please approve flows

[undergroundwires]

It's approved and this is really a great job. I did not see it was such automated and clean solution. 👏. Let me know if there's configs I should add. Pipelines look fine but it's still extremely hard to review due to sad GitHub behavior after force pushes. Or did you create #16 to continue from there? Otherwise I can fix them all if you grant me permissions (see how in docs).

[ag6ag1]

how can we get the pdf version?

[shafr]

@ag6ag1 - go to the actions page & find on the left side the correct format for you (A5 or A4) click on the job & download on the bottom

[shafr]

@undergroundwires probably you can go on & merge this pull request - if something fails - i'll do another PR t ofix that.
Only check that is failing now - is due to permissions from branch.

[undergroundwires]

But it if I merge this now, it will introduce changes and corrupt the history. Or am I interpreting this merge completely wrong? Here's what GitHub reports as changes in this PR, which actually do not belong to this PR:

I see that you do a merge which is very good. But does not seem to solve this issue.

You just need to run single command to fix all these git rebase origin/master -Xtheirs and then run git push -f if it looks right.

However, this has been hanging for a while and I want to merge this. I will do a manual squash and merge for this PR if you do not wish to rebase.

Before I do that, do you have any idea why the action is failing with 403?

[shafr]

I think the to merge it safely - I'll split this pull request into few, so it can be gradually merged.

• If I remember it correctly - all the structure changes were related to website-posting.
• linting jobs can be merged now so you would know if there are some broken links
• PDF generations with a structure would take the most - i'll try to find time for that.

[undergroundwires]

@shafr , the structure changes are OK. But this branch got changes that you never did. Check this one for example. I don't think that you introduced that. We just need to get rid of these changes that GitHub introduced f$£354 this PR up... Smaller PRs would also be nice.

We should grab a beer and celebrate when we can finally get this on master 😀

[shafr]

Closing in favor of #21