rust - How to conveniently host a crate's up-to-date documentation? -


i published first crate on crates.io , wondering if can maintain documentation in easier way.

quite few crates' docs hosted on github pages, thought give shot. created user.github.io repo, generated docs cargo doc , pushed them it. worked fine, docs can viewed crates.io.

however, updating them inconvenient; if modify crate's documentation, need to:

  1. push these changes crate's repo
  2. generate updated docs via cargo doc
  3. move docs' files github page's folder
  4. push docs documentation's repo

i'm pretty sure i'm not doing right - point 3. can simplify process? there better way?

for many crates, docs.rs solution. describes itself as:

docs.rs (formerly cratesfyi) open source project host documentation of crates rust programming language.

docs.rs automatically builds crates' documentation released on crates.io using nightly release of rust compiler.

this has tradeoffs:

  • documentation automatically generated , hosted you, don't have opt-in.
  • documentation each version of crate available.
  • if have platform-specific conditional compilation, documentation different platforms can shown.
  • only released versions of crates documented. can't publish typo in docs without new release.
  • you beholden third-party entity continue providing service.
  • you cannot (currently?) control feature flags used.

some people prefer have more control on documentation, or otherwise don't fall target audience docs.rs. many of cases choose configure ci infrastructure generate documentation , push result somewhere.

a common implementation of use travis ci , github pages many projects use these services. ci system , html hosting service can used, long comfortable connecting two.

the general concept is:

  1. add step build documentation in ci.
  2. when type of build detected, push generated documentation hosting service.
    • possible choices type of build: branch; master branch; tag; etc.
    • be careful avoid exposing credentials. common mistake (that have made myself) use command git push https://${gh_token}@github.com/.... if command fails, token printed stderr, exposing world. other less-obvious cases expose token on failure, check thoroughly.

some people have published blog posts detailing how set things up. have not verified of these sane, may contain details configure specific solution.


Comments

Post a Comment

Popular posts from this blog

How to understand 2 main() functions after using uftrace to profile the C++ program? -

i trying uftrace profile following simple c++ program: #include <iostream> class { public: a() {std::cout << "a created" << std::endl;} ~a() {std::cout << "a destroyed" << std::endl;} }; int main() { a; return 0; } the profile result this: # uftrace a.out created destroyed # duration tid function 2.026 [ 4828] | __cxa_atexit(); [ 4828] | main() { [ 4828] | __static_initialization_and_destruction_0() { 89.397 [ 4828] | std::ios_base::init::init(); 0.768 [ 4828] | __cxa_atexit(); 93.029 [ 4828] | } /* __static_initialization_and_destruction_0 */ 94.425 [ 4828] | } /* main */ [ 4828] | main() { [ 4828] | a::a() { 11.104 [ 4828] | std::operator <<(); 10.825 [ 4828] | std::basic_ostream::operator <<(); 24.514 [ 4828] | } /* a::a */ [ 4828] | a::~a() { 0.978 [ 4828] | ...
Read more

c# - Update a combobox from a presenter (MVP) -

i using mvp in project, new in mvp. have 2 comboboxes. when select option in combobox, combobox should filled new data. this action in presenter. view 'view1' in presenter, , introduced combobox1 , combobox2 properties in 'view1', because need 'datasource', 'displaymember', 'valuemember' , 'refresh()' in method below. but, when using pattern, enough send property like public string combobox2 { { return combobox1.selectedvalue.tosstring(); } } into presenter not whole combobox. how can solve problem? public void onselectedindexchangedcombobox1() { if (view1.combobox1.selectedindex == -1) { return; } datatable dt = tools.getdatatable("a path"); var query = (from o in dt.asenumerable() o.field<string>("afield") == farmerview.combobox1.selectedvalue.tostring() orderby o.field<string>("anotherfield") select...
Read more

How to put a lock and transaction on table using spring 4 or above using jdbcTemplate and annotations like @Transactional? -

i trying put lock on table while writing on table , if happened in between roll-back . trying convert below code lock table test_g1 read; lock table test_g write; -- begin; start transaction; insert test_g1 values(143); insert test_g values(145); select * test_g1; select * test_g; rollback; select * test_g; unlock tables; how convert above code @transactional spring jdbctemplate code? @transactional(rollbackfor={dataaccessexception.class}) public void test(){ jdbctemplate.execute("insert test1 (id, nam) values (4, 'a')"); throw new dataaccessexception("error") { }; } here trying throw error, insert statement should rollback it's not happening . thanks edit-1 attaching code , doing in jdbcdaoimpl.java , mentioned problem comment above test() . app.java package com.cgiri.javabrains.spring4; import org.springframework.beans.factory.annotation.autowired; import org.springframework.context.applic...
Read more