I'm working in a large repo with ~100 individual folders, each with 20-30 sub-folders, each of which contain their own .py folders. Currently I have to create the .rst file for each file using the sphinx-apidoc command, then add the path to the conf.py file then add the .rst file to the index.rst file. Is there anyway of automating this so that all of this is done with just a couple of commands.
The sphinx-autodoc extension states that it will document Python packages. Python packages in turn require that their files (modules) be contained within a directory, and that each directory contain a file with the name of __init__.py.
After you have properly set up your files and directories, then Sphinx can import them and run sphinx-autodoc as expected.
Related
I'm new to Ruby and Jekyll, and I've been following this tutorial on how to create a static-site. I've reached the part where we're supposed to edit files inside the _includes and _layouts folders, but those folders don't appear in my directory. There is however a _site folder with an index.html file inside it, and it looks like that's what's showing when I run the website with 'jekyll serve'. Am I supposed to add these folders and files in myself, or should I edit _site/about/index.html to match what the tutorial has?
Here's a picture of what my current folder structure looks like:
Yes, you should add those folders and files yourself. Copy them from the theme repo and skip anyone you don't want to customize / override. The default theme config created by command jekyll new is https://github.com/jekyll/minima
The _site folder is being generated on the fly, it reflects the result of the customization.
We can add this to rst to create a link to a file :download:`Name <doc/name.pdf>`.
Is it possible for an entire directory? :download:`Dir <doc/>` does not work.
Should it be always pre-archived?
A directory is not a file. The download role:
... lets you link to files within your source tree ... that can be downloaded.
You must make whatever you want to be downloaded downloadable. You would need to tar, zip, or whatever up the files in a directory before building the docs.
I'm trying to set up a Node build system in Sublime Text. I thought I'd use tanepiper's, and I'm following its instructions exactly, but there's a problem: my Node executable isn't found (yes, it's in my system PATH). It says to edit Nodejs.sublime-settings if that happens, but that file is inside Nodejs.sublime-package, which is an archive.
I can't edit the file in-place in the archive. I've tried extracting the archive and then zipping it up again and calling the zip a sublime-package, but that doesn't work either.
So what am I supposed to do here?
You should create Nodejs.sublime-settings in your Packages/User folder. The settings will be merged properly. If you really feel you need to modify the packaged file, use https://github.com/skuroda/PackageResourceViewer, though I'd recommend against it (for settings) as placing a file with the same name in the Packages/User folder will do what you want.
I have a working directory containing my project and it is in a version control system. I'd like to create a doc directory inside my project that contains only restructured text files for sphinx.
That is, I don't want sphinx to build html files inside my project, but put them outside so they don't get put into version control.
So if you question is 'How can I build documentation outside of the source tree', the documentation helps:
sphinx-build -b html sourcedir builddir
Just point builddir to a location outside of your source tree.
Or, depending on your version control system, add the directory you generate your documentation to an 'ignore file' (e.g. .gitignore, .hgignore, ...)
I am trying to structure my ruby project following best practices. I currently have something like this:
test_project/
bin/
test_project # My Executable
lib/
test_project/
my_module.rb
test_project.rb # Loads my_module.rb
I setup it up this way based on recommendations I found on the web.
My problem is I have some resource files, "resouce1.txt" and "resouce2.txt". My executable needs to open the file "resource1.txt". my_module.rb needs to be able to open the file "resource2.txt". Where do I put these plan text resource files in this directory structure and how to I open them (File.open) from the corresponding ruby files.
Since /lib has to do with specifically the Ruby that powers your gems, I would put it in a top-level directory in your gem named after their subject matter. If they are files with lists of species I would call it /species.
You could also go the Rails way and put it in an /assets folder if you have a lot of external assets like /assets/species. Either way, I would not be prone to put them in /lib.
I don't think there is a standard place for these, as for the most part it is operating system dependent (/var and /etc vs Program Files vs the Application Bundle). But your best bet (I think) is to either put them in the root of your hierarchy, put them in lib/ or, if they really are static text files, put them in your script.