{"id":17358295,"url":"https://github.com/yymao/adstex","last_synced_at":"2025-05-16T06:07:50.655Z","repository":{"id":3095222,"uuid":"42411546","full_name":"yymao/adstex","owner":"yymao","description":"Automated generation of NASA ADS bibtex entries directly from citation keys in your TeX source files","archived":false,"fork":false,"pushed_at":"2025-05-12T14:36:55.000Z","size":147,"stargazers_count":178,"open_issues_count":1,"forks_count":15,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-12T14:57:32.365Z","etag":null,"topics":["astronomy","bibliography","bibtex-files","latex","nasa-ads","python"],"latest_commit_sha":null,"homepage":"https://github.com/yymao/adstex#adstex","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yymao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-13T20:24:22.000Z","updated_at":"2025-05-12T14:35:27.000Z","dependencies_parsed_at":"2023-02-14T09:02:00.162Z","dependency_job_id":"344ce872-df0b-403a-bd5a-ad9112c68753","html_url":"https://github.com/yymao/adstex","commit_stats":{"total_commits":105,"total_committers":6,"mean_commits":17.5,"dds":"0.19047619047619047","last_synced_commit":"a7741d1a6877e947269eea265509e7e8f3498c40"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yymao%2Fadstex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yymao%2Fadstex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yymao%2Fadstex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yymao%2Fadstex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yymao","download_url":"https://codeload.github.com/yymao/adstex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478193,"owners_count":22077676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astronomy","bibliography","bibtex-files","latex","nasa-ads","python"],"created_at":"2024-10-15T19:05:01.265Z","updated_at":"2025-05-16T06:07:45.642Z","avatar_url":"https://github.com/yymao.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adstex\n[![Conda Version](https://img.shields.io/conda/vn/conda-forge/adstex.svg)](https://anaconda.org/conda-forge/adstex)\n[![PyPI version](https://img.shields.io/pypi/v/adstex.svg)](https://pypi.python.org/pypi/adstex)\n\nTired of copying and pasting bibtex entries?\nHere's a new way to manage your bibtex entries — do not manage them!\n\n`adstex` automatically identifies all citation keys (e.g., identifiers, author+year)\nin your TeX source files and use\nNASA's [Astrophysics Data System](https://ui.adsabs.harvard.edu/) (ADS)\nto generate corresponding bibtex entries!\n\n`adstex` was featured in an ADS blog post \"[User-Developed Tools for ADS](http://adsabs.github.io/blog/3rd-party-tools)\"!\n\n## Features\n\n- Write your papers without worrying about the bibtex entries.\n  Simply put down arXiv IDs, ADS bibcodes, DOIs, or first author \u0026 year citation keys\n  in your `\\cite` commands,\n  and then use `adstex` to automatically generate the bibtex file for you.\n\n- `adstex` recognizes all variants of the `\\cite` commands,\n  and works with various styles of citation keys.\n  For example, `adstex` would work with all the following:\n  ```tex\n  \\citet{2404.14498}\n  \\citep[e.g.,][]{Mao:Geha:2021, Drlica‑Wagner2019}\n  \\citealt{10.1093/mnras/stx3111, 2024ApJ...976..118G}\n  ```\n\n- `adstex` works along with your existing bibtex files.\n  It simply skips (or updates) those citation keys that already have corresponding bibtex entries.\n\n- `adstex` will also update existing bibtex entries for you!\n  Citing an arXiv preprint which is now published in a journal?\n  No problem, `adstex` will detect this and automatically update the bibtex entry.\n  (_This is amazing, yes, I know!_)\n\n- `adstex` also detects citation keys that actually refer to the same paper\n  (e.g., you use an author:year citation key but another collaborator uses an\n  arxiv ID as key for the same paper),\n  and will prompt you to fix these issues.\n\n\n## Installation and Setup\n\n### Install `adstex`\n\nYou can install `adstex` from conda-forge\n\n```bash\nconda install adstex --channel conda-forge\n```\n\nOr from PyPI\n\n```bash\npip install adstex\n```\n\n### Set up an ADS API token\n\n`adstex` requires an API token to use ADS. Here's how to obtain one:\n\n1. Visit [NASA/ADS](https://ui.adsabs.harvard.edu/) to [sign up for an account](https://ui.adsabs.harvard.edu/user/account/register) if you don't have one.\n\n2. Visit the [API Token page](https://ui.adsabs.harvard.edu/user/settings/token), log in with your ADS account and you will see an API token string. Copy that token string.\n\n3. Set your token string to an environment variable named `ADS_API_TOKEN`. You can do that by running:\n    ```bash\n    # If you use bash or bash-like shells --\n    export ADS_API_TOKEN=\"your token string here\"\n    ```\n    ```csh\n    # If you use csh or csh-like shells --\n    setenv ADS_API_TOKEN \"your token string here\"\n    ```\n    You can put this line into your `~/.bashrc` or `~/.cshrc` file.\n\n\n## Usage\n\nOnce you finish the paper (_sorry, can't help with that!_), simply run `adstex`\nwith the following command (_Internet connection is needed for `adstex` to work._):\n\n```bash\nadstex your_tex_source.tex\n```\n\n`adstex` will automatically build the bibtex files, and write to the bibtex\nsource that you specified in your tex source file.\n\n- If you want to have more control on the output file (or if you are using adstex v0.2.x), use the `-o` option:\n  ```bash\n  adstex your_tex_source.tex -o your_bib_source.bib\n  ```\n  Once `adstex` is done, it will write all bibtex entries in the file\n  that you specified with the `-o` option.\n\n- You can also provide multiple TeX source files at once:\n  ```bash\n  adstex your_tex_source1.tex [your_tex_source2.tex [...]] -o your_bib_source.bib\n  ```\n\n- For citation keys that are arXiv IDs, ADS bibcodes, or DOIs,\n  `adstex` will automatically find the corresponding bibtex entries.\n\n- For first author + year citation keys, `adstex` will search on NASA ADS and\n  provide you a list of candidate papers to select from.\n  If you don't see the paper you are looking for, you can\n  directly enter an ADS bibcode or arXiv ID when prompted.\n\n\n### Optional arguments\n\nHere are some useful optional arguments that you can specify.\nYou can also find a complete option list by running:\n```bash\nadstex --help\n```\n\n- `--use-coauthors` (new in v0.6.0): Use coauthors in the citation key in the ADS search.\n   The citation keys should have the format of `firstauthor:coauthor1:coauthor2:year`.\n\n- `--include-physics`: Include the physics database when searching `author:year` on ADS.\n  Without this option, only the astronomy database is used.\n\n- `--parallel`: Enable multiple threads to speed up the ADS search.\n\n- `--no-update`: Ignore all keys that are already in the bib file.\n  This option will speed up the search, but will not update any arXiv papers that are published in journals.\n\n- `--no-backup`: Do not generate the backup bib file when running `adstex`.\n\nIf you want to set any of these optional features as the default behavior,\nyou can set the `ADSTEX_ARGS` environment variable in your `~/.bashrc` or `~/.cshrc` file.\nHere's an example:\n\n```bash\n# If you use bash or bash-like shells --\nexport ADSTEX_ARGS=\"--use-coauthors --include-physics --parallel\"\n```\n```csh\n# If you use csh or csh-like shells --\nsetenv ADSTEX_ARGS \"--use-coauthors --include-physics --parallel\"\n```\n\nWhen running `adstex`, you can add `--ignore-env-args` to ignore everything set in `ADSTEX_ARGS`.\n\n\n## FAQs\n\n1. **Can `adstex` recognize citation keys with multiple authors or compound surnames?**\n\n   Not always; `adstex` uses [regular expression](https://en.wikipedia.org/wiki/Regular_expression), not AI.\n\n   For citation keys with multiple authors, if you use a separator to separate\n   the surnames, (e.g., `\\cite{Press:Schechter:1974}`), `adstex` will be able to\n   identify the first author and year to conduct a search on the ADS.\n   If you want `adstex` to also use the coauthor in the citation key (in this example, Schechter),\n   please add the `--use-coauthors` argument when running `adstex`.\n\n   For compound surnames, your best bets are\n   joining the words without the spaces (e.g., `\\cite{deSitter:1913}`), and\n   keeping the hyphens (e.g., `\\cite{Boylan-Kolchin:1913}`).\n\n   Note that in the event that `adstex` cannot find the correct paper from a\n   first author + year citation key, it will prompt you to enter an identifier\n   (ADS bibcode, arXiv ID, or DOI) for that key.\n\n\n2. **I have some other bibtex files, how to ask `adstex` to skip citation keys that already have existing entries in those files?**\n\n   Use the `-r` option to provide additional existing bibtex files.\n   `adstex` will read in these files without modifying them\n   (only the file specified by `-o` will be modified). Here's an example command:\n\n   ```bash\n   adstex main.tex -o main.bib -r software.bib classic.bib\n   ```\n\n3. **How do I use `adstex` as a reference manager? Or can I use `adstex` with other reference managers (e.g., JabRef, Mendeley, Zotero)?**\n\n    `adstex` is not a reference manager, and will not be one.\n    The philosophy behind `adstex` is to *not* manage the references,\n    because NASA's ADS is already doing that for us (and is doing an excellent job)!\n    So `adstex` simply generates the bibtex file using the ADS on the fly.\n\n    If you are already using a reference manager, you may want to continue to use it to generate bibtex files. You can then use `adstex` to fetch just the new entries (see FAQ #2).\n    You can also use `adstex` to update all existing entries with the latest version from the ADS by running:\n    ```bash\n    adstex your_bibtex_file.bib\n    ```\n\n4. **Does this work with the ADS astronomy database only?**\n\n   For citation keys that are arXiv IDs, ADS bibcodes, or DOIs,\n   `adstex` would work with any entry as long as it is in the ADS.\n\n   For first author + year citation keys, by default `adstex` would only\n   search the astronomy database on NASA ADS.\n   However, you can use `--include-physics` to include the ADS physics database.\n\n   `adstex` only works with the ADS, and hence the name of this program :)\n\n5. **`adstex` seems to run very slowly. Is there any way to speed it up?**\n\n   By default, `adstex` check if existing entries have any updates\n   (e.g., arXiv preprint becoming a journal paper), and this process may slow\n   down the execution.\n   You can use `--no-update` to turn this feature off,\n   so that `adstex` will only look for new entries.\n\n   In addition, you can turn on parallel execution by adding the `--parallel` (`-p`)\n   option. You can further specify the number of threads it uses with\n   `--threads=x` (default is 8).\n\n6. **I have different citation keys that point to the same paper in my tex file,\n   can `adstex` merge and remove the repetitions?**\n\n   `adstex` will warn you (near the end of its execution) if it detects multiple\n   keys that point to the same paper. It will list all those citation keys, but\n   it will *not* merge them automatically. `adstex` never edits the tex source files;\n   hence, you need to update the citation keys in the tex source files manually.\n\n7. **Is there a way to use `adstex` with Overleaf?**\n\n   If you or your institution has an Overleaf subscription, you can use Overleaf's\n   git or Dropbox integration to fetch the source files to your local machine,\n   run `adstex` locally, and then push back to Overleaf via git\n   (in the case of Dropbox, no pushing needed).\n\n   If you don't have access to Overleaf's premium features, you can still just\n   download the tex source file and bib file, run `adstex` locally, and then upload\n   the updated bib file back to Overleaf (tex source file will not be changed by `adstex`).\n\n8. **I got a `SSLCertVerificationError`! How to fix it?**\n\n   This error usually happens when the ADS SSL certification has been updated,\n   but your local SSL certification has not yet. The error should go away once the\n   local certification is updated too.\n\n   With `adstex` 0.4.0+, you can use the `--disable-ssl-verification` option to\n   temporarily disable the verification of SSL certification. This option can be\n   handy if you don't have control of your local SSL certification installation.\n   Note that with this option, your ADS API key may be vulnerable to a\n   man-in-the-middle attack. You can generate new ADS API key on\n   [ADS website](https://ui.adsabs.harvard.edu/user/settings/token) if you think\n   your API key may have been compromise.\n\n9. **`adstex` saves me so much time. How do I acknowledge it?**\n\n   First of all, thank you :)\n\n   `adstex` won't exist without NASA's ADS, so please do acknowledge them by\n   adding the following to your acknowledgements section:\n   ```tex\n   This research has made use of NASA's Astrophysics Data System.\n   ```\n   (_Note: `adstex` is not affiliated with nor endorsed by NASA's ADS._)\n\n   Then, if you would like to also acknowledge `adstex`, you can add\n   the following to your acknowledgements section:\n   ```tex\n   This research has made use of adstex (\\url{https://github.com/yymao/adstex}).\n   ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyymao%2Fadstex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyymao%2Fadstex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyymao%2Fadstex/lists"}