Add manual page generation to Sphinx docs

[Rycieos]

Add mappings for config, functions, and theme to manual page sections. Install does not have a mapping, mostly because to get the manual pages you already need to have installed Liquidprompt. Though that does leave out how to install Liquidprompt into the shell. But maybe it is something that packages should include instructions for, since each package installs liquidprompt and the example config files to different locations.

Attached is a gzip of the compiled man pages: liquidprompt.man.tar.gz

CC: @aborrero, @augmentedfourth

Any ideas of how to ship these files?

[augmentedfourth]

It looks like, if these files are inserted in the repo as share/man/man[357]/liquidprompt.[357], Homebrew will automatically do the needful, extracting and symlinking them to places where the OS will be able to find them. But, if you want to include them in a different place in the repo, I could write code in the formula to deploy the symlinks manually.

[augmentedfourth]

But that's only based on documentation, not experience. I haven't actually done this before.

[Rycieos]

I don't want to commit compiled files to the repo, but I could add a Github action to build the files using Sphinx and attach them as release artifacts I think. I'll try to build something like that.

[augmentedfourth]

Hm. OK. The install formula I've written for Homebrew expects the git checkout (for HEAD installs from the master branch) to include basically the same thing as a release tarball. I might have to rethink some of the installation code if that changes. If the release tarball included the man pages in the location specified above, then people running the release should get them just fine, but if there's a way to generate them from within the repo I might be able to compile them as part of the HEAD installation as well.

In looking into this, I've also noticed that all my Homebrew formula does is install symlinks to liquidprompt and liquidpromptrc-dist in /usr/local/share/ (as well as provide instructions upon installation for how to modify your shell profile and migrate/copy the rc file to your homedir). There's no special treatment of any other files, like the zsh plugin, so those stay in the "Cellar" that contains the git clone/extracted tarball and aren't linked anywhere common that might be useful. I don't know if any of those files should be made available, as I've personally been running it in bash with just the script itself for at least 8 years (I first committed the Homebrew install formula in March 2013, and was definitely using it before then). Should I look into expanding the installation and making it easier to find more of the release files in common directories?

Note that any files in the release tarball located in share/ are documented to be installed automatically without the specific install code in my formula (e.g. if you want to put the script and the stock rc file in there), but again any divergence between the structure of the release tarball and the repo itself will necessitate changes to the formula.

[Rycieos]

All good points.

Should I look into expanding the installation and making it easier to find more of the release files in common directories?

Yes, probably. The example files should probably be easy to find in a /share or similar.

That's not to say that we couldn't package our own release tarballs, putting the example files in a /share of some sort and the compiled man pages in the right place too. And even liquidprompt under /lib. And while we are at it, why not start splitting liquidprompt into multiple files, since it is over 2000 lines of code now. If we are compiling releases, we could, and when compiling, concat them all to one sourceable file again.

This is still in the spitballing stage...

[Rycieos]

I added a Github Actions file that will create a new release when a tag is pushed matching v*, create a zipfile with the manual pages, and attach that to the release. I did test it, but don't want to publish a release to prove it.

Obviously this is a separate zip file containing just the manual pages, but we can add more advanced release tarballs once we know the format that is needed.

[augmentedfourth]

OK, cool. I'd be curious to know:

1. Which files from the repo/release should be made available - and maybe where?
   • Note that liquidprompt is currently installed in /usr/local/share/ because Homebrew had some pretty strict rules about what types of artifacts should go where, and they were least stringent about what could go in "share." I'm not sure I want to argue with them to do something different, especially because the usage instructions have had the current path for as long as it's been available.
2. How would I go about having users of the HEAD/master direct-clone installation compile the man pages themselves? Would that require Sphinx on everyone's local system?

[Rycieos]

No idea for 1. But I agree, don't change how it is now.

2. It is a Python module, so anyone with Python 3 can build the docs. But I wouldn't want to make users do that if possible. Of course anyone can view the HTML docs online (liquidprompt.readthedocs.io). But it would be nice to find a solution for git cloners as well.

[augmentedfourth]

So I'm not sure as I've never used these files, but it seems that liquid.ps1, liquid.theme, and liquidprompt.plugin.zsh are ones that might be useful for Homebrew to distribute. They seem to be an example, a modifiable default, and a usage pattern respectively.

Are these correct? Should anything else be included? Maybe themes/powerline/powerline.theme?

And should I include anything in contrib/ to show how Homebrew is set up? Note that I use linuxbrew to install liquidprompt on Ubuntu, and it installs things in slightly different places (by default, /home/linuxbrew/.linuxbrew/share/liquidprompt), but the installation/usage instructions are modified dynamically to support how that homebrew fork works.

[Rycieos]

• liquidprompt.plugin.zsh is pretty important for loading Liquidprompt as a Zsh plugin. Though I'm not sure if anyone who uses it as such would install it with Homebrew instead of using a dedicated Zsh plugin manager.
• liquid.ps1 is an example template file. As noted on the top of the file, it will not exactly match the default theme, so it should probably not be used as is. Therefore it should be included strictly as an example. I don't know where exactly that would be.
• liquid.theme is also an example, but specifically for how to modify the colors and markers of the default theme. Same as above, it will not exactly match the default theme, so it should probably not be used as is. Therefore it should be included strictly as an example.
• themes/ are new (in v2.0) included themes that should be on par with the default theme. I would include them in some way.
• contrib/ seems to not have anything relating to Homebrew, so I don't see a reason for it to be included.
• tools/ is not strictly needed, but going forward if users report issues with data sources on their machines, I'll be asking them to post the output of tools/external-tool-tester.sh to help debug the issue (and create test cases to prevent regressions). So it should be available somehow.

Probably liquid.ps1, liquid.theme, example.bashrc, and liquidpromptrc-dist should all be included as examples.

Building the docs with Sphinx is pretty straightforward, as long as you have Python 3.5 or newer:

cd docs/
virtualenv venv --python=python3 && . venv/bin/activate
pip install -r requirements.txt
make man
cp -r _build/man output

[aborrero]

the manual page is useful in the debian package. Ideally you would ship it in the same tarball like the rest of the release source code.

[Rycieos]

Ideally you would ship it in the same tarball like the rest of the release source code.

Any opinions on where to put it? It would be simple to leave it in docs/_build/man/, but that doesn't seem ideal.

[aborrero]

Ideally you would ship it in the same tarball like the rest of the release source code.

Any opinions on where to put it? It would be simple to leave it in docs/_build/man/, but that doesn't seem ideal.

That's OK. I can work with that. Perhaps the most important point is that whatever the path is, it remains stable for years to come.

[augmentedfourth]

As I stated above, if you put the man pages in share/man/man[357]/liquidprompt.[357], Homebrew should pick them up and publish them automatically. But, as @aborrero mentions above, I should be able to tweak the formula to handle anything.

[Rycieos]

I added two more commits that build a release tarball instead of the man pages zip file. It is pretty much just the whole repo, plus the compiled manual pages in docs/_build/man/. Here is an example:
liquidprompt-vtemp.tar.gz

I'm pretty happy with this, so unless there is something organizationally that you can't work with, I'll be merging this.

[Rycieos]

I just released v2.0.0-rc.1 which has a tarball attached. The format of this tarball won't change between now and the full release, so if you want to test your packaging let me know if you have any issues.

[augmentedfourth]

A PR for bumping to v2.0.0 is now in Homebrew: Homebrew/homebrew-core#70536
There appear to be Homebrew CI failures because it's attempting to run the script as an executable rather than sourcing it, and I'm looking into how I might be able to resolve this ro their satisfaction.

Unfortunately, the formula as I wrote it all those years ago is based on downloading/extracting the source tarball and not the release tarball. I'll need to update the Homebrew formula to pull the release tarball instead, and provide different instructions for installing the man pages when installing a release version. For now, I'll just have it install as usual.

[Rycieos]

I'm afraid we already have a v2.0.1 😞

[augmentedfourth]

No problem. It hasn't been merged yet, so I updated the PR to 2.0.1. Still wrestling with the homebrew maintainers about what constitutes an appropriate Ruby test for a tool they likely know nothing about. 😕

[Rycieos]

@augmentedfourth I don't want to pollute the Homebrew issue, so I'll ask here:

Wouldn't you want to download the new tarball that contains the manual pages?
Link for the latest release is: https://github.com/nojhan/liquidprompt/releases/download/v2.0.1/liquidprompt-v2.0.1.tar.gz

As for the test, obviously running it as a script is going to fail, as the test shows. You could try sourcing it instead:

shell_output("/bin/sh -c '. #{liquidprompt}'")

but since no terminal will be attached, it will immediately exit.

You could use the --no-activate flag that we use for our tests, which will bypass that exit, and also will not install Liquidprompt, just load all the functions:

shell_output("/bin/sh -c '. #{liquidprompt} --no-activate'")

But again, there won't be any output. If you need to have some output string to test, maybe this would work:

shell_output("/bin/sh -c '. #{liquidprompt} --no-activate; lp_theme --list'")

Which should only return the string default\n.

I would prefer to only test return codes, so we don't end up changing some output string and breaking tests. I don't know if Homebrew can do that, but this could maybe work?

shell_exit_code("/bin/sh -c '. #{liquidprompt} --no-activate; lp_theme --list'")

[augmentedfourth]

Yes, I do want to use the new release tarball, as I mentioned above. I haven't had time to figure out how exactly that would change the format of the formula, so I was going to just bump the version with the old formula for now.

I'll look into updating the test as well. I honestly don't know anything about how the test was originally generated or inserted (aside from the username of the account that contributed it, but it doesn't seem to be connected to the project at all).

[Rycieos]

v2.0.2 is out. Looks like there is no update on the Homebrew PR? 😞

It looks like the only packages updated to 2.0.X yet is AUR. That makes me slightly worried about hidden bugs with low numbers of testers 😕

[augmentedfourth]

I haven't had time to work on it, unfortunately. It's on my to-do list, but various other commitments haven't left me with enough left over to finish this.

At least anyone who's using the --HEAD target in Homebrew (like I am) is already updated to whatever's in master. I'd imagine that those are the sorts of users who would be most likely to test & submit reports/requests.

[augmentedfourth]

It turns out that the shell_output function in Homebrew already checks the exit code and defaults to requiring 0: https://github.com/Homebrew/brew/blob/b024954a0f203a4f439cc95eefb1180c96e943ce/Library/Homebrew/formula_assertions.rb#L60

I updated this to check for the text output of lp_theme --list. The automated tests seem to be succeeding, so hopefully it passes this time.

[augmentedfourth]

2.0.2 Homebrew PR is accepted!