I typically use certain extensions such as sphinxcontrib.bibtex with every Sphinx documentation project, which means I need to add the extension to the conf.py file for each project.
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage',
'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode',
'sphinxcontrib.bibtex']
Is there a simple what of including these by default in conf.py?
You could create a module containing your default settings, and then import them into your configuration file.
However, unless you are working on the project alone, it's probably better to always include the full configuration in a project so that other people working on it know they are building it with the same settings.
Another alternative might be to create a template configuration file with those settings that you could use for new projects.
Related
In the documentation about sphinx extensions are some "config values". e.g. in sphinx.ext.autodoc.
But I do not know how to set these values. Is it a parameter on the shell I have to set?
There's a page on the docs that teaches how to use extensions. The page is here: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
In this page you have the following description:
A list of strings that are module names of extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.
This tells you that sphinx.ext.* are the built-ins extensions (You can confirm that from here)
Basically when it states some kind of configuration, it refers to the conf.py file that is generated when you run sphinx-quickstart, which is a quick-setup command for sphinx in general (Might be a good read: https://www.sphinx-doc.org/en/master/usage/quickstart.html)
The root directory of a Sphinx collection of plain-text document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation.
Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you.
Note that, as it's built-in, it's already setupped with your sphinx project.
But if you want to customize it somehow, you can use conf.py file with autodoc_* configurations (As listed here)
There are also some notes that might be useful for your case
For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly.
I read about Git integration in PyCharm, and created a Git repository from PyCharm. I did this in PyCharm because I was hoping PyCharm would know whether the .idea folder should be ignored, and if that's the case, it would automatically create a .gitignore file with the line .idea/ in it.
But it didn't, so I assumed that I shouldn't ignore the .idea foler. However, I did a quick search and found someone's example .gitignore file, here, which clearly ignores the .idea folder.
So, my question is, should the .idea folder be ignored or not?
Ignoring the whole .idea folder is not necessarily the best idea. There's a number of similar discussions here about this.
How to deal with IntelliJ IDEA project files under Git source control constantly changing?
Intellij Idea 9/10, what folders to check into (or not check into) source control?
Should the .idea folder be kept under source control?
But I suggest to check the official FAQ on this matter.
All the settings files in the .idea directory should be put under
version control except the workspace.xml, which stores your local
preferences. The workspace.xml file should be marked as ignored by
VCS.
-PyCharm 2017.3 project documentation
To explain further, workspace.xml contains user-specific workspace preferences. This includes environment variables, recently accessed files, and cursor position.
While sharing your project settings isn't inherently a bad idea, there are several exceptions and potential issues you should be aware of.
The workspace.xml file contains various user-specific settings, such as environment variables, cursor position, and Python SDK location.
Environmental variables may include private data, such as usernames and passwords
The dictionaries folder contains custom spellings, which can cause conflicts if two developers have the same name.
The .idea folder is PyCharm specific, meaning developers using a different IDE can lead to project desynchronization.
IntelliJ's own documentation includes several warnings for specific files that shouldn't be shared.
If you do decide to share .idea, IntelliJ's official documentation gives the following advice
[The .idea] format is used by all the recent IDE versions by default.
Here is what you need to share:
All the files under .idea directory in the project root except the workspace.xml and tasks.xml files which store user specific settings
All the .iml module files that can be located in different module directories (applies to IntelliJ IDEA)
Be careful about sharing the following:
Android artifacts that produce a signed build (will contain keystore passwords)
In IDEA 13 and earlier dataSources.ids, datasources.xml can contain database passwords. IDEA 14 solves this problem.
You may consider not to share the following:
.iml files for the Gradle or Maven based projects, since these files will be generated on import
gradle.xml file, see this discussion
user dictionaries folder (to avoid conflicts if other developer has the same name)
XML files under .idea/libraries in case they are generated from Gradle or Maven project
Source: JetBrains - How to manage projects under Version Control Systems
I found some issue when include whole .idea/ directory into project.
If you push to git repo including .idea/ directory, and clone that project on other machine with pycharm, pycharm can't recognize the project appropriately.
After delete .idea/ directory, pycharm recognize the project well.
The .idea/ folder is just the way that JetBrain's stores data. It's in IntelliJ and PyCharm, so, yes, it can be ignored.
I have an issue where I am developing a Django project which includes other libraries we are also developing.
My current structure is as follows:
Main Project
App1
App2
Libraries
Library 1
Library 2
All libraries have their own setup scripts and are in separate git repositories, and we are adding them in PyCharm in the PYTHONPATH, and referencing them simply by their name. Which works good, but they are not in my current project, which means no re-factoring ( renaming, moving etc... ) and I have to use External search to find my class from the libraries.
How do I set some libraries as project related to make them view-able and refactorable like we do on the currently set project.
Well, you can add other directories as content roots:
Then simply mark the directory as a source root:
This should allow you to refactor, rename and do all the things you've wanted to do.
Another option would be to place libraries into separate project (or go even further and place each library in its own project) and then open this project/these projects side-by-side with the main project. This way you have clear separation between the main project and libraries used. This comes handy when you work on another project using some of the same libraries as then you only need to open already existing project containing libraries and you are done.
Ok, so I have been looking around and I have seen a couple different options although i am new to python so i am a bit confused. Here is what I am looking for:
I have a project of multiple .py files. I have my files and a lib directory for the libraries i have created. My question is, how do i setup the project to have a version? I see a lot of articles saying that I put the version in setup.py. Where does setup.py go? what else needs to be in that setup.py file? Do I just import setup.py into my python files? How can i check to see if it worked? How can i check the version of each .py file to make sure it imported correctly?
Read hitchhiker's guide to packaging to learn good practice for developing a Python project
The setup.py file is at the heart of a Python project. It describes all of the metadata about your project. There a quite a few fields you can add to a project to give it a rich set of metadata describing the project. However, there are only three required fields: name, version, and packages. The name field must be unique if you wish to publish your package on the Python Package Index (PyPI). The version field keeps track of different releases of the project. The packages field describes where you’ve put the Python source code within your project.
Our initial setup.py will also include information about the license and will re-use the README.txt file for the long_description field. This will look like:
from distutils.core import setup
setup(
name='TowelStuff',
version='0.1dev',
packages=['towelstuff',],
license='Creative Commons Attribution-Noncommercial-Share Alike license',
long_description=open('README.txt').read(),
)
Typically a project will include it's version as an __version__ attribute within its top level namespace.
For example:
>>> import myproject
>>> print myproject.__version__
'3.2.0'
See http://www.python.org/dev/peps/pep-0396/ for more info and ways to access __version__ from within your setup.py file.
Is there a standard file in python which lists all the modules comprising the project, and other metadata?
Is this simply the 'package'? Or, do different IDEs use their own specific files?
There really isn't a single file in any package that consistently lists every module the entire package imports. Some people make entries to the __init__.py and some don't. Usually most python supported IDE's will make available to you whatever is on your pythonpath. Eclipse pydev, for instance, will add the specific project to the pythonpath of that project space.
If your project is on the pythonpath, then it should resolve.
Application builders like py2app/py2exe will scan the entire project and create an import graph to discover every module needed for that project
There's no real equivalent in Python by itself. Python packages are the way to encapsulate a set of modules and include metadata, but it isn't exactly equivalent to the notion of a "project."
Otherwise, are some projects which use project files in order to give you some of the features which IDEs provide. In particular, you should check out the rope library and the PyCharm IDE for some systems which implement a project file.