I am trying to use a README.md file with JSDoc when launching jsdoc I get the following error.
ERROR: Unable to parse /Users/patrick/workflow/README.md: Topic reference is used, but the pipelineOperator plugin was not passed a "proposal": "hack" or "smart" option. (1:0)
My README file does seem correct.
Any idea on how to solve the issue ?
# Foobar
Foobar is a Python library for dealing with word pluralization.
## Installation
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.
```bash
pip install foobar
```
## Usage
```python
import foobar
# returns 'words'
foobar.pluralize('word')
# returns 'geese'
foobar.pluralize('goose')
# returns 'phenomenon'
foobar.singularize('phenomena')
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
## License
[MIT](https://choosealicense.com/licenses/mit/)
I deleted the modules directory and reinstalled it. All good, now.
Related
I have the following in my setup.cfg file:
[project.urls]
"Documentation" = "https://pysui.readthedocs.io"
"Bug Reports" = "https://github.com/FrankC01/pysui/issues"
My build executes without error and twine check and twine upload work without a hitch. However, the extra links do not show up in PyPi?
I think that format works only with the pyproject.toml as described at https://packaging.python.org/en/latest/tutorials/packaging-projects/#configuring-metadata . Note, the above describes how it works when using pypa's build for building, other packaging tools use their own ways to define this information.
If you prefer to use setup.cfg, you could try adding the project_urls under [metadata] like this:
[metadata]
project_urls =
Documentation = https://pysui.readthedocs.io
Bug Reports = https://github.com/FrankC01/pysui/issues
One more tip: you can check the PKG-INFO file in the created tar archive to see that the information was added correctly:
Project-URL: Documentation, https://pysui.readthedocs.io
Project-URL: Bug Reports, https://github.com/FrankC01/pysui/issues
I'm trying to find a way to make VSCode Python intellisense work with Airflow Plugins.
Following the code example the import path of plugin operators could be:
from airflow.operators import MyPluginOperator
VSCode cannot resolve this import because it will only be valid at runtime through the airflow plugin system.
Is there any way to configure VSCode to resolve this import?
Airflow loads plugins dynamically by searching the airflow/plugins folder for AirflowPlugin subclasses and add them in airflow namespace in a runtime. Here is the code from airflow/operators/__init__.py:
# Imports operators dynamically while keeping the package API clean,
# abstracting the underlying modules
...
def _integrate_plugins():
"""Integrate plugins to the context"""
from airflow.plugins_manager import operators_modules
for operators_module in operators_modules:
sys.modules[operators_module.__name__] = operators_module
globals()[operators_module._name] = operators_module
VS Code can't handle it. Even "big" Python IDEs like PyCharm has problems with it. It is impossible for VS Code to know that a piece of code in particular folder will transform in airflow.operator later. "python.autoComplete.extraPaths" will not help too. You should only hope that someone will write a VS Code extension for Airflow somewhere :)
Since version 2.0.0 the way that Airflow handles plugins imports has changed:
Importing operators, sensors, hooks added in plugins via airflow.{operators,sensors,hooks}.<plugin_name> is no longer supported, and these extensions should just be imported as regular python modules. For more information, see: Modules Management and Creating a custom Operator
The next important thing to consider is that Airflow adds dags/, plugins/, and config/ directories to PYTHONPATH env. source
Following the specifications from the docs, you could create your MyCustomOperator
in airflow_home/plugins/custom_operator/ directory. Then you could use it like this:
from custom_operator.my_custom_operator import MyCustomOperator
with dag:
sample_custom_task = MyCustomOperator(task_id='sample-task')
So far so good, the dag will run, but according to my experience, the VSCode IntelliSense won't work yet. To make it work, you need to add the path to /plugins as same as Airflow will do when it runs. Depending on your setup there are a few ways to do this. The goal is to add an extra path to the python interpreter VSCode is "using" (make sure to select the interpreter related to your project)
A common solution could be to use the env PYTHONPATH to append our path to the path the interpreter knows. In my case, I'm using a virtual environment, so following the explained in this post, I created a .pth file with the path I wanted to add and locate that file on airflow_home/venv/lib/my_python_version/site-packages/
Following the path on our example, this will create such a file:
cd $(python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())")
echo airflow_home/plugins > airflow_plugins_example.pth
Once that is done, reload VSCode (could also just change to another interpreter and then come back) and you should see the intelliSense working properly.
Hope that works!
I have written the documentation for a medium sized C++ piece of software using Doxygen together with Markdown. I am quite happy with it, as after changing the xml layer I ended up with something like that:
http://docs.mitk.org/nightly/index.html
I would like to bring this documentation online, ideally using something like ReadtheDocs, where the documentation would be automatically built after a "git commit", and hosted to be browsed.
ReadtheDocs looks like the ideal site but uses Sphinx and reStructuredText as defaults. Doxygen can be used too, but AFAIK only through Breathe. Going through that route essentially means that I would need to re-structure all the documentation if I don't want to dump all the API documentation into a single page (http://librelist.com/browser//breathe/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f).
Paradoxically, Doxygen is installed in the read-the-docs server, but after struggling I could not find a workaround to skip its Sphinx or Mkdocs.
I've tried the following solution to use Doxygen on Read The Docs and it seems to work:
set up empty sphinx project (refer to official sphinx doc),
in sphinx conf.py add command to build doxygen documentation,
use conf.py html_extra_path config directive to overwrite generated doxygen documentation over generated sphinx documentation.
I've tested this with following source tree:
.../doc/Doxyfile
/build/html
/sphinx/conf.py
/sphinx/index.rst
/sphinx/...
Some explanation:
in my setup doxygen generates its documentation in "doc/build/html",
ReadTheDocs runs its commands in directory where it finds conf.py file.
What to do:
add following lines in conf.py to generate doxygen docs:
import subprocess
subprocess.call('cd .. ; doxygen', shell=True)
update conf.py html_extra_path directive to:
html_extra_path = ['../build/html']
In this configuration ReadTheDocs should properly generate and store Doxygen html documentation.
todo:
other documentation formats, for example: pdf.
This answer builds upon the great one already given by "kzeslaf". So follow the steps described by him first, before you continue here.
While his answer works as intended, I had the problem that ReadTheDocs (RTD) uses a rather old version of Doxygen (1.8.13 at the time of writing). This caused several issues for me like the one reported here. Additionally, if you set up Doxygen to treat warnings as errors, you might need to override this option on RTD due to version-related warnings.
I found a simple solution to upgrade the Doxygen version on RTD using conda.
Create an environment.yml file somewhere in your project (probably in the documentation directory). The content is as follows:
name: RTD
channels:
- conda-forge
- defaults
dependencies:
- python=3.8
- doxygen=<VERSION>
Replace <VERSION> with any version number that you like to use and that is available on conda-forge. Use conda search doxygen -c conda-forge to get a list of all available versions or simply check this site. You can also remove =<VERSION> and conda should install the latest one automatically.
Now you need to create an RTD config file if you haven't done this already. Add the following lines:
conda:
environment: <DIRECTORY>/environment.yml
Replace <DIRECTORY> with the actual location of the environment.yml file (relative to your project root, for example: docs/environment.yml). Now, if you followed all the steps in the answer of "kzelaf" and the ones I mentioned, RTD should successfully build your Doxygen documentation with the version you selected. You can check it in the lower right corner of the created pages. Alternatively, add subprocess.run(["doxygen", "-v"]) to your conf.py and check the RTD build logs.
I've created a library on myget (part of ci), and I'm trying to push the symbol sources to symbolsource.org (this is a great service, and I love the idea). This is my first attempt. I've been using the instructions found on the myget site: http://docs.myget.org/docs/reference/symbolsource, but there are some gaps.
Here are the steps I go through. First, I create a nuspec file, and I use "nuget pack -symbol xxx" to create the X.symbols.nupkg and X.nupkg files. This works just fine. I then push them individually to myget and symbolsource. I used the nuget pkg explorer to examine the contents, and they look as I would expect (the src, pdb, and dll show up in the symbols). After doing the push, I can log into symbolsource and I see my packages up there using the instructions found on the myget page.
I used the following command to push to symbolsource:
nuget push X.symbols.nupkg $ApiKey -Source http://nuget.gw.SymbolSource.org/MyGet/rootdotnet/
I then configure visual studio as instructed: make sure to turn off "enable just my code" and also to turn on symbol servers. I then add to the list of symbol servers the following URL:
http://srv.SymbolSource.org/pdb/MyGet/gwatts/XXXXX
Where XXXX is a GUID I read off the sumbolsource "Your Account"/"Authentication" "Visual Studio" table entry (myget wasn't at all clear this is what I was supposed to do).
I then try to debug. When I hit something in that library, I get the "No Symbols Loaded" page in VS2012. Under details, there is a dump VS2012's attempt to find the pdb file. I see the following:
C:\Users\Gordon\Documents\Code\HVQCDCorrelationStudy\CalcSimpleCorrelationTestNumbers\bin\x86\Debug\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
c:\TeamCity\buildAgent\work\44463130cd7383cb\LINQToTTree\LINQToTTreeLib\obj\x86\Release\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
C:\WINDOWS\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
C:\WINDOWS\symbols\dll\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
C:\WINDOWS\dll\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
C:\Users\Gordon\AppData\Local\Temp\SymbolCache\LINQToTTreeLib.pdb\9c883e0fa93245c99efd2b92dbfc6dfc1\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
C:\Users\Gordon\AppData\Local\Temp\SymbolCache\MicrosoftPublicSymbols\LINQToTTreeLib.pdb\9c883e0fa93245c99efd2b92dbfc6dfc1\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
C:\Users\Gordon\Documents\Code\HVQCDCorrelationStudy\LINQToTTreeLib.pdb: Cannot find or open the PDB file.
SYMSRV: C:\Users\Gordon\AppData\Local\Temp\SymbolCache\LINQToTTreeLib.pdb\9C883E0FA93245C99EFD2B92DBFC6DFC1\LINQToTTreeLib.pdb not found
SYMSRV: http://srv.SymbolSource.org/pdb/MyGet/gwatts/XXXXX/LINQToTTreeLib.pdb/9C883E0FA93245C99EFD2B92DBFC6DFC1/LINQToTTreeLib.pdb not found
http://srv.SymbolSource.org/pdb/MyGet/gwatts/XXXXX: Symbols not found on symbol server.
SYMSRV: C:\Users\Gordon\AppData\Local\Temp\SymbolCache\LINQToTTreeLib.pdb\9C883E0FA93245C99EFD2B92DBFC6DFC1\LINQToTTreeLib.pdb not found
SYMSRV: http://msdl.microsoft.com/download/symbols/LINQToTTreeLib.pdb/9C883E0FA93245C99EFD2B92DBFC6DFC1/LINQToTTreeLib.pdb not found
http://msdl.microsoft.com/download/symbols: Symbols not found on symbol server.
In short, it looks like it correctly contacts symbolssource.org. But something is failing up there. The 9C883E0FA93245C99EFD2B92DBFC6DFC1 is obviously a hash. I have no idea (??) what hash symbolssource assigned to that library - though I'd love to try to figure it out, as that might be a first step to understanding what is going on.
Basically. I don't know how to proceed with debugging at this point. Any help would be appreciated!
Update: As mentioned in the answers below, build something small that can be tested. I've done that, and it works just fine. In doing that I discovered there are some debugging tools up on SymbolSource.org - specifically, when you look at a package in your feed, you can find the "Compilations" link. Click on it. It should show a line for each build type you've uploaded. My packages have nothing associated with that - so I've messed up my nuspec file somehow for symbol generation.
Try to isolate a reproducible scenario (rule out as many other factors as you can). Sounds like your Visual Studio set up is correct, so I'm suspicious for package or compilation issues (e.g. symbols and sources out of sync). Feel free to contact MyGet support for further assistance.
The answer, it turns out, is a slice of humble pie. Turns out on my build server there was an environment variable conflict. The result was that local build scripts built a symbols file just fine and the build server built one without PDB's in it. Without pdb's, of course, the source server was not able do very much.
One thing I did learn on the way is the NuGet PackageExplorer (https://npe.codeplex.com/). Want you can do is use it to load up the nugget symbols package. Then use the plug-in manager to load in the SymbolesSource plug-in (you'll have to use the market place, but it is all free). This utility would have caught the problem in my packages had I submitted the proper ones to it (my local packages passed with flying colors).
How does one do a relative import from a parent directory?
From meme/cmd/meme:
import "../../../meme"
This gives an ambiguous error:
matt#stanley:~/gopath/src/bitbucket.org/anacrolix/meme/cmd/meme$ go get bitbucket.org/anacrolix/meme/cmd/meme
can't load package: /home/matt/gopath/src/bitbucket.org/anacrolix/meme/cmd/meme/main.go:8:2: local import "../../../meme" in non-local package
matt#stanley:~/gopath/src/bitbucket.org/anacrolix/meme/cmd/meme$ echo $GOPATH
/home/matt/gopath
How do I import locally from a parent directory?
Edit: Relative import paths are not the way to go in Go. Lack of documentation shows something about popularity of relative paths, and I don't see a reason for using them. Go's recommended code organization works pretty well. Every package should have a unique import path and be imported everywhere using that same import path.
See how a package like github.com/ha/doozerd/peer imports its neighbors. This is a common practice among Go projects and I've seen it a lot of times. Package camlistore.org/pkg/auth (also on GitHub; written by one of the main authors of Go) imports camlistore.org/pkg/netutil by full path.
Even if you are having both commands and libraries in the same project this approach works. In your original questions you wisely asked for best practices. I did my best in explaining best practices on this matter.
Import paths can't be relative in Go. I recommend reading How to Write Go Code, the essential reading on organizing Go projects. Here's a short overview:
Make a directory like ~/go for your Go development. Then say:
$ export GOPATH=~/go
$ mkdir $GOPATH/{src,bin,pkg}
$GOPATH/src holds source code for all your Go packages, even the ones your download with go get. bin and pkg keep output of compilations. Packages with package name main are commands and yield to executable binaries which go to $GOPATH/bin. Other packages are libraries and their compiled object files are put in $GOPATH/pkg.
Now if you put your code in $GOPATH/src/matt/meme, you can import it by import "matt/meme". It's recommended to use a prefix for your package names and leave short package names for standard libraries. That's why I used $GOPATH/src/matt/meme instead of $GOPATH/src/meme.
Organize your code around this idea.
Thanks for adding to your question. First, an answer, then some explanation. I built your code by,
go get, just as you had it. (I ignored the error messages.)
setting the import line in main.go back to "../../../meme", as you wanted to do.
(commenting out a little bit of code containing an unused variable.)
then in the meme/cmd/meme directory, either go run main.go or go build main.go worked.
I was wrong in my comment earlier when I said go install works; I should have said go build.
The key however is that go build alone does not work; you must type go build main.go. This is because the go command does not allow "local imports in non-local packages." You are right that spec is of little help here. It weasels out saying, "The interpretation of the ImportPath is implementation-dependent." The current implementation behavior was set with CL 5787055, which was subsequently debated at length on Go-nuts.
"Local" means indicated with a file system relative path. Obviously a relative path starting with .. is local, so the trick is just getting the go command to treat main as a local package as well. It apparently doesn't do this when you type go build, but does when you type go build main.go.
Relarive imports are supported when manually using the compiler, linker, ... directly. The 'go' (build) tool doesn't support the same (somehow comparable to eg Java).
This may not answer the original question, but I was trying to do the above when I didn't really need to, all I needed to do was update go.mod temporarily with a replace :
module github.com/pselle/foo
replace github.com/pselle/bar => /Users/pselle/Projects/bar
require (
github.com/pselle/bar v1.0.0
)
reference:
https://thewebivore.com/using-replace-in-go-mod-to-point-to-your-local-module/