openindiana / oi-docs

Work in progress OpenIndiana documentation

OpenIndiana Docs

A new home for OpenIndiana docs, made with mkdocs.

License

This project is under the PDL license, unless stated otherwise in individual files.

Authors

• A. Gordon
• Adam Števko
• Adrian Lucrèce Céleste (Previously known as: Theodore Seán Tubbs)
• Alexander Pyhalov
• Benny
• Johnathan "ShaggyTwoDope" Jenkins
• Lucas Sköldqvist
• Michael Kruger
• David Stes
• /u/127b
• Andreas Wacknitz

Depends

• mkdocs

Depends for linting

• mdl
• mdspel

oi-docs's Issues

Transition of docs site to production

Things which should be done to make documentation site official:

• Move all actual and relevant content of current handbook to new version.
• Review new handbook content to avoid actual errors.
  • Review and mark existing Wiki handbook content as either obsolete or suitable for importation.
  • For items marked for importation insert placeholder link into new handbook referencing page(s) on Wiki to be imported.
  • Import content and mark imported content as a draft version.
  • Research and fix any obvious technical errors, when done, mark as ready for technical review.
  • Solicit technical reviews of items marked as ready for technical review.
• Make look and feel of http://www.openindiana.org/ and documentation site similar.
  • Compare sites and create a list of areas which need work
  • Research what needs to change and how to change it.
  • Implement changes.
• Investigate process for exporting docs as PDF and EPUB
  Need to look into what tools might work for this, and document the process for doing it.
  https://github.com/jgrassler/mkdocs-pandoc
• Provide links to illumos documentation, open zfs documentation where necessary.

This is likely something which would be addressed during technical reviews as a part of the content importation process.

SMF documentation

It would be nice to incorporate some of these questions into oi-docs: http://bnsmb.de/solaris/My_Little_SMF_FAQ.html

No docs on how to simply connect through PPPoE to my isp

Ubuntu has the very nice and simple pppoeconf app exactly for the purpose of dealing with pppoe. In the OpenIndiana docs I only found references to pppd. That is as far as I could understand from reading 'man pppd' a way to build scripts on top of raw network protocols. I am willing to put on the effort to help create some sort of simple to use script to solve the issue of connecting to my ISP. If anyone could guide me through such an effort I would appreciate it.

Typos in the "Storage Archive Manager handbook" (samqfs.md)

While reading, I encountered these typos:

It is reommended to save the metadata of the filesystem (inodes) for situations where you have to recover the SamFS filesystem.

• samqfs.md, line 320: 's/reommended/recommended/'

To much CLI for you?

• samqfs.md, line 326: 's/To/Too/'

I'm not sure if this is an improvement, but:
'There is a more comfortable termbased tool /opt/SUNWsamfs/sbin/samu.'
can be written as:
'There is a more comfortable TUI-based tool /opt/SUNWsamfs/sbin/samu.'

Splitting existing pages into multiple pages

The Getting Started and Systems Administration pages have a lot of content packed into a single page. This doesn't seem like the best way to organise things.
In particular there is still content on ZFS and Virtualization that could be migrated from the old Wiki. There are placeholders in the docs where this could go, but it would make the pages even longer.
It seems like the content could be split across a few more pages, so that storage and zones/virtualization could have their own pages.

Move notes section of docs site to the wiki

There are a few docs here which are internal notes with suggestions for improvement, how to deal with the OSOL docs, a look at the BSD's for inspiration, etc.

Update the docs to reflect the new method for creating USB flash drives

• Account for both the old and new methods.
• Explain how the method to use depends on whether the release being written to the drive.
• Look into whether the new DD method would also work on Windows.

Approach for Adding Pull Request & PDF Build support to GitHub Actions

At the moment GitHub Actions (added in #191) is only triggered by a push to master and it always builds and deploys. We don't get any build status indicators on PRs.

We should add a new workflow which is triggered by Pull Requests and runs just the linting and mkdocs build (not deploy). We could do this by creating a new branch from the OI mkdocs-deploy-gh-pages action. This would be identical but with deployment commands removed. A new workflow would then be configured to use that branch and run on pull requests only.

Compared to Travis which was used previously, GH Actions doesn't automatically build PRs from first time contributors, so a maintainer will need to approve these manually.

In addition to this, we could build the PDF versions of doc pages (using makepdf.sh) and add these to the website. This is straightforward to configure using the (upload/download)-artifact actions. There's no appropriate existing action for the PDF build. We could create one, this would require a whole new repo specially for that action. The main benefit of actions is reuse and we will need to reuse the code for building PDFs - in both a potential PR build workflow and the deploy workflow.

I would therefore suggest:

1. A new branch is added to OI mkdocs-deploy-gh-pages for PR builds, it could be called oi-pr.
2. A. A new repo under the OI project is created for holding a GH Action for building the PDFs, or
   B. PDF build is configured and run directly from the workflow yaml - avoiding the need for an action but introducing some duplication.
3. A new workflow is created for PR builds (including PDF build) and PDF build is added to the current deploy workflow.

Of the options 2A and 2B, I think 2B is probably better - when balancing the extra work of creating and maintaining a separate repo for the action, against using the workflow yaml directly.

Update docs to reflect the new desktop and desktop manager, etc.

• Account for differences introduced by the mate desktop (lightdm, mate apps, etc.)

Update site parameters per changes in mkdocs 0.16

http://www.mkdocs.org/about/release-notes/#version-016-2016-11-04

Problems with makepdf.sh and general suitability of docs for PDF conversion

Since makepdf.sh was last updated, pandoc has deprecated the form of the command used in the script. This is easily fixed but the resulting PDFs are not very good. Defaults are used for everything. The paper size has the large default LaTex margins, tables are crushed with overlapping text, hyperlinks are not colored or missing (if inline HTML was used), among other problems. The makepdf.sh script itself is not documented or mentioned on the getting started page.

Unfortunately it's not possible to fix the above problems with a small update to the script and docs. Pandoc is used for the conversion from markdown to PDF (via LaTex) and this doesn't support the mix of html and markdown which is used in many of the pages. Some pages also have problems with extraneous HTML tags. These don't cause an issue with MkDocs but do with Pandoc - e.g. docs/books/advanced.md has an incorrect </p> tag inside various tables, which prevents the tables from generating.

I can see two ways to fix this:

1. The proper fix - Go through the docs and replace all inline HTML with equivalent markdown (e.g. hyperlinks with markdown links) if the HTML is intended to be used in the PDF. This is required because Pandoc suppresses all HTML when using the LaTex output mode.
2. The quick fix - Change the script to add an extra step where Pandoc produces HTML output first and then converts that to PDF (via LaTex). This would in effect be a conversion of: [markdown -> HTML] plus [HTML -> markdown -> LaTex -> PDF]. This would fix the existing problems of a mix of markdown and HTML formatting. But it would come at the cost of much increased processing time and loss of certain formatting which doesn't convert well between markdown -> HTML.

I've not looked at how much work would be involved for 1. In addition to the above, I would suggest adding Pandoc formatting options to color hyperlinks, use normal margins and I'd also suggest using a san-serif font.

I'm happy to have a go at fixing the problem and submitting a PR. But considering the work involved and the number of changes that might be required, I thought it would be best to raise an issue explaining the problem first. Rather than making a large PR for work that is not wanted - OI might not be interested in having PDF versions of the docs.

Remove sudo from examples

Browsing the documentation I noticed the use of 'sudo' in the examples. I think a better convention would be to use '#' to indicate a command that must be invoked with more privileges than a regular user. '$', '%', or similar would be used to indicate a command run as a regular user.

Examples:

# dd bs=4M if=./image.usb of=/dev/sdX status=progress && sync

$ vmstat

The FreeBSD Handbook mentions it in its preface.

Text installer limiting domainname to 15c

(This may be the wrong place to put this, but with slim_source having no blurb to point at a better place and no issues there, I'm arguing that the problem can at least go into documentation if it remains unfixed :)

The text installer has a input limit to the domainname, stopping at char 15. Since not everyone is privileged to a 3-letter domainname, this is quite a showstopper, even though there are a number of possible workarounds, most of them adding a lot of extra steps to the task.

One possible "solution" would be to predefine the host in DHCP (and jump through the subsequent hooks of getting rid of the dhcp config afterwards, if undesired)

OSDisc.com has closed, remove mentions from the documentation

As it can be seen in this forum post, OSDisc.com has closed.
Therefore, all mentions can be removed from the documentation.
Affected files:

• docs/misc/openindiana.md
• docs/handbook/getting-started.md

Wrong formatting in `docs/dev/userland.md`

I have spotted that In section Creating Makefile there is wrong format of example (bash syntax and # instead of = is used). It also has wrong indentation.

dd command on OSX does not have "status" operand

The dd command shown in http://docs.openindiana.org/handbook/getting-started/#creating-a-hipster-usb-drive for copying the usb image to disk on BSD or OSX does not work on OSX as is. OSX dd does not have a "status=" operand.

Document zpool installation

Need to explain how to install OpenIndiana to existing pool using text installer and what caveats exist.

Update Theme to be able to update mkdocs in OI repo

@JMadgwick In the monthly maintainer meetup the age of our mkdocs package in oi-userland came up. I see we are using GitHub Actions so it wouldn't impact the docs directly if we update now but I also saw #220 so we would need to update the theme to make be able to update our mkdocs for docs. I think we should start of working on these things, so we can keep up to date with the docs pages. Whats your opinion?

@cstes here the reference issue

Document zone-proxyd

Need to document zone-proxyd usage and existing issues.

Add a separate page to the contrib section titled - Working with GIT

Provide basic instructions for working with git, for example commonly used commands, etc.