search

jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
511 stars 45 forks source link

Mike fails to deploy #203

Closed djacu closed 5 months ago

djacu commented 5 months ago

Summary

I am trying to use mike on my local machine to test out building different versions of the docs. Whenever I try to run mike deploy <version>, I get an error.

Configuration and Logs

$ mike deploy 0.1.0
ERROR   -  Config value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs
ERROR   -  Config value 'markdown_extensions': Failed to load extension 'pymdownx.tasklist'.
           ModuleNotFoundError: No module named 'pymdownx'
ERROR   -  Config value 'plugins': The "blog" plugin is not installed

Aborted with 3 configuration errors!
error: Command '['mkdocs', 'build', '--clean', '--config-file', 'mkdocs.yml']' returned non-zero exit status 1.

Steps to Reproduce

I am using nix for my dev environment but you could just as easily use pip or poetry to install the dependencies.

  1. git clone https://github.com/djacu/nixcv
  2. nix develop .#site
  3. cd site
  4. mike deploy 0.1.1

Expected Behavior

I expected mike to create a new commit on the default branch.

Additional Context

I have run the command at the end of the error message and it builds fine.

$ mkdocs build --clean --config-file mkdocs.yml
INFO    -  [macros] - Macros arguments: {'module_name': 'main', 'modules': [], 'render_by_default': True, 'include_dir': '', 'include_yaml': [],
           'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': '', 'on_undefined': 'keep',
           'on_error_fail': False, 'verbose': False}
INFO    -  [macros] - Extra variables (config file): ['social', 'version']
INFO    -  [macros] - Extra filters (module): ['pretty']
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/bakerdn/dev/djacu/nixcv-mike/site/site
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - documentation/modules/biblatex/common.md
             - documentation/modules/enumitem/setlistOptions.md
             - documentation/modules/templates/default.md
             - documentation/modules/templates/misc.md
             - documentation/modules/templates/defaults/simple.md
INFO    -  Documentation built in 0.81 seconds
jimporter commented 5 months ago

This looks like something went awry with your environment. I'd recommend cloning mike locally and adding some instrumentation to where it calls out to MkDocs to verify that all your environment variables are as expected and that it's picking the right instance of mkdocs (assuming you have more than one on your system).

djacu commented 5 months ago

The entire environment is sandboxed in the nix store. mike should only be able to see the version of mkdocs bundled in that environment.

As you can see, mike and mkdocs are both located in the same sandbox.

% nix develop .#site
$ cd site
$ which mkdocs
/nix/store/r29j7dl2fdfpkj7yzbw13qlwwg8s8l8f-python3-3.11.6-env/bin/mkdocs
$ which mike
/nix/store/r29j7dl2fdfpkj7yzbw13qlwwg8s8l8f-python3-3.11.6-env/bin/mike

Just to make sure that all the correct python packages are available. mkdocs, mike, material, pymdownx, etc are all available as python modules.

$ python
Python 3.11.6 (main, Oct  2 2023, 13:45:54) [GCC 12.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> help('modules')

Please wait a moment while I gather a list of all available modules...

PIL                 _weakref            heapq               runpy
__future__          _weakrefset         hmac                sched
__hello__           _xxsubinterpreters  html                secrets
__phello__          _xxtestfuzz         http                select
_abc                _yaml               idlelib             selectors
_aix_support        _zoneinfo           idna                shelve
_ast                abc                 imaplib             shlex
_asyncio            aifc                imghdr              shutil
_bisect             antigravity         imp                 signal
_blake2             argparse            importlib           site
_bootsubprocess     array               importlib_metadata  sitecustomize
_bz2                ast                 importlib_resources six
_cffi_backend       asynchat            inspect             smtpd
_codecs             asyncio             io                  smtplib
_codecs_cn          asyncore            ipaddress           sndhdr
_codecs_hk          atexit              itertools           socket
_codecs_iso2022     audioop             jinja2              socketserver
_codecs_jp          babel               json                spwd
_codecs_kr          base64              keyword             sqlite3
_codecs_tw          bdb                 lib2to3             sre_compile
_collections        binascii            linecache           sre_constants
_collections_abc    bisect              locale              sre_parse
_compat_pickle      builtins            logging             ssl
_compression        bz2                 lzma                stat
_contextvars        cProfile            mailbox             statistics
_crypt              cairocffi           mailcap             string
_csv                cairosvg            markdown            stringprep
_ctypes             calendar            markupsafe          struct
_ctypes_test        certifi             marshal             subprocess
_curses             cffi                material            sunau
_curses_panel       cgi                 materialx           symtable
_datetime           cgitb               math                sys
_dbm                charset_normalizer  mergedeep           sysconfig
_decimal            chunk               mike                syslog
_elementtree        click               mimetypes           tabnanny
_functools          cmath               mkdocs              tarfile
_gdbm               cmd                 mkdocs_macros       telnetlib
_hashlib            code                mmap                tempfile
_heapq              codecs              modulefinder        termcolor
_imp                codeop              multiprocessing     termios
_io                 collections         netrc               test
_json               colorama            nntplib             textwrap
_locale             colorsys            ntpath              this
_lsprof             compileall          nturl2path          threading
_lzma               concurrent          numbers             time
_markupbase         configparser        opcode              timeit
_md5                contextlib          operator            tinycss2
_multibytecodec     contextvars         optparse            tkinter
_multiprocessing    copy                os                  token
_opcode             copyreg             ossaudiodev         tokenize
_operator           crypt               packaging           toml
_osx_support        cssselect2          paginate            tomllib
_pickle             csv                 pathlib             trace
_posixshmem         ctypes              pathspec            traceback
_posixsubprocess    curses              pdb                 tracemalloc
_py_abc             dataclasses         pickle              tty
_pydecimal          datetime            pickletools         turtle
_pyio               dateutil            pipes               turtledemo
_queue              dbm                 pkgutil             types
_random             decimal             platform            typing
_sha1               defusedxml          platformdirs        unicodedata
_sha256             difflib             plistlib            unittest
_sha3               dis                 poplib              urllib
_sha512             distutils           posix               urllib3
_signal             doctest             posixpath           uu
_sitebuiltins       email               pprint              uuid
_socket             encodings           profile             venv
_sqlite3            ensurepip           pstats              verspec
_sre                enum                pty                 warnings
_ssl                errno               pwd                 watchdog
_stat               faulthandler        py_compile          wave
_statistics         fcntl               pyclbr              weakref
_string             filecmp             pycparser           webbrowser
_strptime           fileinput           pydoc               webencodings
_struct             fnmatch             pydoc_data          wsgiref
_symtable           fractions           pyexpat             xdrlib
_sysconfigdata__linux_x86_64-linux-gnu ftplib              pygments            xml
_testbuffer         functools           pymdownx            xmlrpc
_testcapi           gc                  pyparsing           xxlimited
_testclinic         genericpath         queue               xxlimited_35
_testimportmultiple getopt              quopri              xxsubtype
_testinternalcapi   getpass             random              yaml
_testmultiphase     gettext             re                  yaml_env_tag
_thread             ghp_import          readline            zipapp
_threading_local    glob                regex               zipfile
_tokenize           graphlib            reprlib             zipimport
_tracemalloc        grp                 requests            zipp
_typing             gzip                resource            zlib
_warnings           hashlib             rlcompleter         zoneinfo
djacu commented 5 months ago

I tried adding the --verbose flag to see if there was any more details that could be provided but it appears broken.

$ mike --verbose deploy 0.1.0
usage: mike [-h] [--version] [--debug] COMMAND ...
mike: error: unrecognized arguments: --verbose
jimporter commented 5 months ago

I tried adding the --verbose flag to see if there was any more details that could be provided but it appears broken.

mike doesn't have a --verbose flag.

Loading MkDocs plugins (including pymdownx) works fine for me locally though; ditto with custom themes. However, I don't use Nix, so I just installed the Python packages via pip. Unfortunately, I can't help you with anything Nix-related, so you're on your own in that regard.

Cloning mike (and possibly MkDocs) to add instrumentation on your end would probably help to narrow down where things are going wrong. In particular, you'd want to make sure that mike is actually calling the right mkdocs with the right environment variables (and that mkdocs in turn sees all the right env vars). It's possible there's a bug in mike, though the code in question is pretty simple, so I'd be surprised.

djacu commented 5 months ago

mike doesn't have a --verbose flag.

That's totally my bad. Got mike and mkdocs mixed up during debugging.

djacu commented 5 months ago

Tried this with a stateful version of poetry running via Nix. It all appears to work normally so this must be some weirdness going on within the nix store.

Thanks for the help.

% nix develop .#poetry
$ cd site/
$ poetry env list
nixcv-site-Mhk-AimF-py3.11 (Activated)
$ poetry run mike deploy 0.1.0
INFO    -  [macros] - Macros arguments: {'module_name': 'main', 'modules': [], 'render_by_default': True, 'include_dir': '', 'include_yaml': [],
           'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': '', 'on_undefined': 'keep',
           'on_error_fail': False, 'verbose': False}
INFO    -  [macros] - Extra variables (config file): ['version', 'social']
INFO    -  [macros] - Extra filters (module): ['pretty']
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/bakerdn/dev/djacu/nixcv-mike/site/site
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - documentation/modules/biblatex/common.md
             - documentation/modules/enumitem/setlistOptions.md
             - documentation/modules/templates/default.md
             - documentation/modules/templates/misc.md
INFO    -  Documentation built in 0.91 seconds
$ poetry run mike list
0.1.0