Merge pull request #82 from zuzukin/doc

Add check for doc links (#81)

Makefile

@@ -1,6 +1,7 @@
 RM := rm
 RMDIR := rm -rf
 DEV_ENV := whl2conda-dev
+TOUCH := touch
 
 ifdef OS
 	# Windows
@@ -46,6 +47,7 @@ help:
 	"\n" \
 	"--- documentation ---\n" \
 	"doc           - build documentation\n" \
+	"doc-strict    - build documentation and check links\n" \
 	"doc-open      - build/open documentation index.html\n" \
 	"doc-serve     - serve documentation in temporary web server\n" \
 	"doc-serve-all - serve versioned documentation in temporary web server\n" \
@@ -135,6 +137,12 @@ site/index.html: $(CLI_DOCS) $(MKDOCS_FILE) doc/*.md src/whl2conda/api/*.py
 
 doc: site/index.html
 
+site/.doc-strict: site/index.html
+	$(CONDA_RUN) linkchecker -f likcheckerrc.ini site
+	$(TOUCH) $@
+
+doc-strict: site/.doc-strict
+
 doc-serve: $(CLI_DOCS)
 	$(CONDA_RUN) mkdocs serve -f $(MKDOCS_FILE)
 

doc/install.md

@@ -1,14 +1,23 @@
 
-## using pip
+## Using pip
 
 ```bash
 pip install whl2conda
 ```
 
-## using conda
+## Using conda
 
 ```bash
 conda install -c conda-forge whl2conda
 ```
 
+*whl2conda* does not have a direct runtime dependency on conda, so it
+is safe to install in environments other than `base`.
+
+## Prerequisites
+
+It is assumed that you have installed conda, and that it is in the program
+path, but it is currently only required for `whl2conda install`. Furthermore,
+if you use the `--conda-bld` option, you must have `conda-index` installed
+in your base environment (you will already have it if you have `conda-build`).
 

doc/limitations.md

@@ -1,9 +1,43 @@
 *whl2conda* currently only supports conversion of generic pure python wheels
 into noarch python conda packages.
 
-It has the following limitations, some of which might be addressed in future
+It has the following limitations, some of which will be addressed in future
 releases.
 
+## Version specifiers are not translated
+
+Version specifiers in dependencies are simply copied from
+the wheel without modification. This works for many cases,
+but since the version comparison operators for pip and conda
+are slightly different, some version specifiers will not work
+properly in conda. Specifically,
+
+* the *compatible release* operator `~=` is not supported by conda.
+    To translate, use a double expression with `>=` and `*`, e.g.:
+    `~= 1.2.3` would become `>=1.2.3,1.2.*` in conda. This form is
+    also supported by pip, so this is a viable workaround for packages
+    you control.
+
+
+* the *arbitrary equality* clause `===` is not supported by conda.
+    I do not believe there is an equivalent to this in conda, but
+    this clause is also heavily discouraged in dependencies and
+    might not even match the corresponding conda package.
+
+(*There are other operations supported by conda but not pip, but
+the are not a concern when translating from pip specifiers.*)
+
+As a workaround, users can switch to compatible specifier syntax when
+possible and otherwise can remove the offending package and add it
+back with compatible specifier syntax, e.g.:
+
+```bash
+whl2conda mywheel-1.2.3-py3-none-any.whl -D foo -A 'foo >=1.2.3,1.2.*'
+```
+
+This will be fixed in a future release 
+(see [issue 84](https://github.com/zuzukin/whl2conda/issues/84)).
+
 ## Cannot convert from sdist
 
 Currently, only conversion from wheels is supported. Conversion from python sdist

environment.yml

@@ -26,4 +26,6 @@ dependencies:
   - mkdocstrings-python >=1.3,<2.0
   - mkdocs-material >9.1
   - mkdocstrings-python-xref >=1.5.2,<2.0
+  - linkchecker >=10.2.1
+
 

linkcheckerrc.ini

@@ -0,0 +1,7 @@
+# configuration for linkchecker for use on site/
+[filtering]
+checkextern=1
+# ignore URLs that we cannot access without authentication
+#ignore=
+#  https://fonts.gstatic.com
+#  https://anaconda.org

mkdocs.yml

@@ -32,8 +32,8 @@ nav:
       - License: license.md
 
 # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
-extra_css:
-  - style.css
+#extra_css:
+#  - style.css
 
 theme:
   name: material